stackube/vendor/github.com/emicklei/go-restful-swagger12

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.

© 2017, ernestmicklei.com. MIT License. Contributions welcome.