Name: emicklei-go-restful-swagger12
Owner: OpenShift
Description: Swagger 1.2 extension to the go-restful package
Forked from: emicklei/go-restful-swagger12
Created: 2017-09-18 14:42:55.0
Updated: 2017-09-18 14:43:29.0
Pushed: 2018-03-21 16:33:38.0
Homepage: null
Size: 27
Language: Go
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
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)
Currently there are 2 ways to document your structs in the go-restful Swagger.
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))"postcode"
and not "PostCode"
)© 2017, ernestmicklei.com. MIT License. Contributions welcome.