initial commit, copied all code from go-restful/swagger here

Change-Id: I35be0b8f7fd8e53404e59f57635deed44068cc51
emicklei · Jan 30, 2017 · d8ee348 · d8ee348
1 parent 79470eb
commit d8ee348
Show file tree

Hide file tree

Showing 22 changed files with 3,574 additions and 1 deletion.
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,4 @@
+language: go
+
+go:
+  - 1.x
diff --git a/CHANGES.md b/CHANGES.md
@@ -0,0 +1,46 @@
+Change history of swagger
+=
+2017-01-30
+- moved from go-restful/swagger to go-restful-swagger12
+
+2015-10-16
+- add type override mechanism for swagger models (MR 254, nathanejohnson)
+- replace uses of wildcard in generated apidocs (issue 251)
+
+2015-05-25
+- (api break) changed the type of Properties in Model
+- (api break) changed the type of Models in ApiDeclaration
+- (api break) changed the parameter type of PostBuildDeclarationMapFunc
+
+2015-04-09
+- add ModelBuildable interface for customization of Model
+
+2015-03-17
+- preserve order of Routes per WebService in Swagger listing
+- fix use of $ref and type in Swagger models
+- add api version to listing
+
+2014-11-14
+- operation parameters are now sorted using ordering path,query,form,header,body
+
+2014-11-12
+- respect omitempty tag value for embedded structs
+- expose ApiVersion of WebService to Swagger ApiDeclaration
+
+2014-05-29
+- (api add) Ability to define custom http.Handler to serve swagger-ui static files
+
+2014-05-04
+- (fix) include model for array element type of response
+
+2014-01-03
+- (fix) do not add primitive type to the Api models
+
+2013-11-27
+- (fix) make Swagger work for WebServices with root ("/" or "") paths
+
+2013-10-29
+- (api add) package variable LogInfo to customize logging function
+
+2013-10-15
+- upgraded to spec version 1.2 (https://github.com/wordnik/swagger-core/wiki/1.2-transition)
diff --git a/README.md b/README.md
@@ -1,2 +1,81 @@
 # go-restful-swagger12
-Swagger 1.2 extension to the go-restful package
+
+[![Build Status](https://travis-ci.org/emicklei/proto3.png)](https://travis-ci.org/emicklei/go-restful-swagger12)
+[![GoDoc](https://godoc.org/github.com/emicklei/proto3?status.svg)](https://godoc.org/github.com/emicklei/go-restful-swagger12)
+
+How to use Swagger UI with go-restful
+=
+
+Get the Swagger UI sources (version 1.2 only)
+
+	git clone https://github.com/wordnik/swagger-ui.git
+
+The project contains a "dist" folder.
+Its contents has all the Swagger UI files you need.
+
+The `index.html` has an `url` set to `http://petstore.swagger.wordnik.com/api/api-docs`.
+You need to change that to match your WebService JSON endpoint  e.g. `http://localhost:8080/apidocs.json`
+
+Now, you can install the Swagger WebService for serving the Swagger specification in JSON.
+
+	config := swagger.Config{
+		WebServices:    restful.RegisteredWebServices(),
+		ApiPath:        "/apidocs.json",
+		SwaggerPath:     "/apidocs/",
+		SwaggerFilePath: "/Users/emicklei/Projects/swagger-ui/dist"}
+	swagger.InstallSwaggerService(config)		
+
+
+Documenting Structs
+--
+
+Currently there are 2 ways to document your structs in the go-restful Swagger.
+
+###### By using struct tags
+- Use tag "description" to annotate a struct field with a description to show in the UI
+- Use tag "modelDescription" to annotate the struct itself with a description to show in the UI. The tag can be added in an field of the struct and in case that there are multiple definition, they will be appended with an empty line.
+
+###### By using the SwaggerDoc method
+Here is an example with an `Address` struct and the documentation for each of the fields. The `""` is a special entry for **documenting the struct itself**.
+
+	type Address struct {
+		Country  string `json:"country,omitempty"`
+		PostCode int    `json:"postcode,omitempty"`
+	}
+
+	func (Address) SwaggerDoc() map[string]string {
+		return map[string]string{
+			"":         "Address doc",
+			"country":  "Country doc",
+			"postcode": "PostCode doc",
+		}
+	}
+
+This example will generate a JSON like this
+
+	{
+		"Address": {
+			"id": "Address",
+			"description": "Address doc",
+			"properties": {
+				"country": {
+				"type": "string",
+				"description": "Country doc"
+				},
+				"postcode": {
+				"type": "integer",
+				"format": "int32",
+				"description": "PostCode doc"
+				}
+			}
+		}
+	}
+
+**Very Important Notes:**
+- `SwaggerDoc()` is using a **NON-Pointer** receiver (e.g. func (Address) and not func (*Address))
+- The returned map should use as key the name of the field as defined in the JSON parameter (e.g. `"postcode"` and not `"PostCode"`)
+
+Notes
+--
+- The Nickname of an Operation is automatically set by finding the name of the function. You can override it using RouteBuilder.Operation(..) 
+- The WebServices field of swagger.Config can be used to control which service you want to expose and document ; you can have multiple configs and therefore multiple endpoints.
diff --git a/api_declaration_list.go b/api_declaration_list.go
@@ -0,0 +1,64 @@
+package swagger
+
+// Copyright 2015 Ernest Micklei. All rights reserved.
+// Use of this source code is governed by a license
+// that can be found in the LICENSE file.
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// ApiDeclarationList maintains an ordered list of ApiDeclaration.
+type ApiDeclarationList struct {
+	List []ApiDeclaration
+}
+
+// At returns the ApiDeclaration by its path unless absent, then ok is false
+func (l *ApiDeclarationList) At(path string) (a ApiDeclaration, ok bool) {
+	for _, each := range l.List {
+		if each.ResourcePath == path {
+			return each, true
+		}
+	}
+	return a, false
+}
+
+// Put adds or replaces a ApiDeclaration with this name
+func (l *ApiDeclarationList) Put(path string, a ApiDeclaration) {
+	// maybe replace existing
+	for i, each := range l.List {
+		if each.ResourcePath == path {
+			// replace
+			l.List[i] = a
+			return
+		}
+	}
+	// add
+	l.List = append(l.List, a)
+}
+
+// Do enumerates all the properties, each with its assigned name
+func (l *ApiDeclarationList) Do(block func(path string, decl ApiDeclaration)) {
+	for _, each := range l.List {
+		block(each.ResourcePath, each)
+	}
+}
+
+// MarshalJSON writes the ModelPropertyList as if it was a map[string]ModelProperty
+func (l ApiDeclarationList) MarshalJSON() ([]byte, error) {
+	var buf bytes.Buffer
+	encoder := json.NewEncoder(&buf)
+	buf.WriteString("{\n")
+	for i, each := range l.List {
+		buf.WriteString("\"")
+		buf.WriteString(each.ResourcePath)
+		buf.WriteString("\": ")
+		encoder.Encode(each)
+		if i < len(l.List)-1 {
+			buf.WriteString(",\n")
+		}
+	}
+	buf.WriteString("}")
+	return buf.Bytes(), nil
+}
diff --git a/config.go b/config.go
@@ -0,0 +1,46 @@
+package swagger
+
+import (
+	"net/http"
+	"reflect"
+
+	"github.com/emicklei/go-restful"
+)
+
+// PostBuildDeclarationMapFunc can be used to modify the api declaration map.
+type PostBuildDeclarationMapFunc func(apiDeclarationMap *ApiDeclarationList)
+
+// MapSchemaFormatFunc can be used to modify typeName at definition time.
+type MapSchemaFormatFunc func(typeName string) string
+
+// MapModelTypeNameFunc can be used to return the desired typeName for a given
+// type. It will return false if the default name should be used.
+type MapModelTypeNameFunc func(t reflect.Type) (string, bool)
+
+type Config struct {
+	// url where the services are available, e.g. http://localhost:8080
+	// if left empty then the basePath of Swagger is taken from the actual request
+	WebServicesUrl string
+	// path where the JSON api is avaiable , e.g. /apidocs
+	ApiPath string
+	// [optional] path where the swagger UI will be served, e.g. /swagger
+	SwaggerPath string
+	// [optional] location of folder containing Swagger HTML5 application index.html
+	SwaggerFilePath string
+	// api listing is constructed from this list of restful WebServices.
+	WebServices []*restful.WebService
+	// will serve all static content (scripts,pages,images)
+	StaticHandler http.Handler
+	// [optional] on default CORS (Cross-Origin-Resource-Sharing) is enabled.
+	DisableCORS bool
+	// Top-level API version. Is reflected in the resource listing.
+	ApiVersion string
+	// If set then call this handler after building the complete ApiDeclaration Map
+	PostBuildHandler PostBuildDeclarationMapFunc
+	// Swagger global info struct
+	Info Info
+	// [optional] If set, model builder should call this handler to get addition typename-to-swagger-format-field conversion.
+	SchemaFormatHandler MapSchemaFormatFunc
+	// [optional] If set, model builder should call this handler to retrieve the name for a given type.
+	ModelTypeNameHandler MapModelTypeNameFunc
+}