Categorygithub.com/emicklei/go-restful-swagger12
modulepackage
0.0.0-20201014110547-68ccff494617
Repository: https://github.com/emicklei/go-restful-swagger12.git
Documentation: pkg.go.dev

# README

go-restful-swagger12

Build Status GoDoc

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.

# Packages

No description provided by the author

# Functions

InstallSwaggerService add the WebService that provides the API documentation of all services conform the Swagger documentation specifcation.
No description provided by the author
RegisterSwaggerService add the WebService that provides the API documentation of all services conform the Swagger documentation specifcation.

# Variables

LogInfo is the function that is called when this package needs to log.

# Structs

5.2.2 API Object.
5.2 API Declaration.
ApiDeclarationList maintains an ordered list of ApiDeclaration.
5.1.5.
5.1.9 Authorization Code Object.
No description provided by the author
4.3.3 Data Type Fields.
5.1.7.
5.1.8 Implicit Object.
5.1.3 Info Object.
4.3.4 Items Object.
5.1.10 Login Endpoint Object.
5.2.6, 5.2.7 Models Object.
ModelList encapsulates a list of NamedModel (association).
5.2.8 Properties Object.
ModelPropertyList encapsulates a list of NamedModelProperty (association).
NamedModel associates a name with a Model (not using its Id).
NamedModelProperty associates a name to a ModelProperty.
5.2.3 Operation Object.
5.2.4 Parameter Object.
5.1.2 Resource Object.
5.1 Resource Listing.
5.2.5 Response Message Object.
5.1.6, 5.2.11.
No description provided by the author
No description provided by the author
5.1.12 Token Endpoint Object.
5.1.11 Token Request Endpoint Object.

# Interfaces

ModelBuildable is used for extending Structs that need more control over how the Model appears in the Swagger api declaration.

# Type aliases

5.2.10.
MapModelTypeNameFunc can be used to return the desired typeName for a given type.
MapSchemaFormatFunc can be used to modify typeName at definition time.
PostBuildDeclarationMapFunc can be used to modify the api declaration map.
No description provided by the author