README
¶
swag
swag is a lightweight library to generate swagger json for Go projects.
No code generation, no framework constraints, just a simple swagger definition.
swag is heavily geared towards generating REST/JSON apis.
Installation
go get github.com/savaki/swag
Status
This package should be considered a release candidate. No further package changes are expected at this point.
Concepts
swag uses functional options to generate both the swagger endpoints and the swagger definition. Where possible
swag attempts to use reasonable defaults that may be overridden by the user.
Endpoints
swag provides a separate package, endpoint, to generate swagger endpoints. These endpoints can be passed
to the swagger definition generate via swag.Endpoints(...)
In this simple example, we generate an endpoint to retrieve all pets. The only required fields for an endpoint are the method, path, and the summary.
allPets := endpoint.New("get", "/pet", "Return all the pets")
However, it'll probably be useful if you include definitions of what GET /pet returns:
allPets := endpoint.New("get", "/pet", "Return all the pets",
endpoint.Response(http.StatusOk, Pet{}, "Successful operation"),
endpoint.Response(http.StatusInternalServerError, Error{}, "Oops ... something went wrong"),
)
Refer to the godoc for a list of all the endpoint options
Walk
As a convenience to users, *swagger.Api implements a Walk method to simplify traversal of all the endpoints.
See the complete example below for how Walk can be used to bind endpoints to the router.
api := swag.New(
swag.Title("Swagger Petstore"),
swag.Endpoints(post, get),
)
// iterate over each endpoint, if we've defined a handler, we can use it to bind to the router. We're using ```gin``
// in this example, but any web framework will do.
//
api.Walk(func(path string, endpoint *swagger.Endpoint) {
h := endpoint.Handler.(func(c *gin.Context))
path = swag.ColonPath(path)
router.Handle(endpoint.Method, path, h)
})
Complete Example
func handlePet(w http.ResponseWriter, _ *http.Request) {
// your code here
}
type Pet struct {
Id int64 `json:"id"`
Name string `json:"name"`
PhotoUrls []string `json:"photoUrls"`
Tags []string `json:"tags"`
}
func main() {
// define our endpoints
//
post := endpoint.New("post", "/pet", "Add a new pet to the store",
endpoint.Handler(handle),
endpoint.Description("Additional information on adding a pet to the store"),
endpoint.Body(Pet{}, "Pet object that needs to be added to the store", true),
endpoint.Response(http.StatusOK, Pet{}, "Successfully added pet"),
)
get := endpoint.New("get", "/pet/{petId}", "Find pet by ID",
endpoint.Handler(handle),
endpoint.Path("petId", "integer", "ID of pet to return", true),
endpoint.Response(http.StatusOK, Pet{}, "successful operation"),
)
// define the swagger api that will contain our endpoints
//
api := swag.New(
swag.Title("Swagger Petstore"),
swag.Endpoints(post, get),
)
// iterate over each endpoint and add them to the default server mux
//
for path, endpoints := range api.Paths {
http.Handle(path, endpoints)
}
// use the api to server the swagger.json file
//
enableCors := true
http.Handle("/swagger", api.Handler(enableCors))
http.ListenAndServe(":8080", nil)
}
Additional Examples
Examples for popular web frameworks can be found in the examples directory:
Documentation
¶
Overview ¶
Copyright 2017 Matt Ho
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright 2017 Matt Ho ¶
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Index ¶
- func ColonPath(path string) string
- func New(options ...Option) *swagger.API
- type Builder
- type Option
- func BasePath(v string) Option
- func ContactEmail(v string) Option
- func Description(v string) Option
- func Endpoints(endpoints ...*swagger.Endpoint) Option
- func Host(v string) Option
- func License(name, url string) Option
- func Schemes(v ...string) Option
- func Security(scheme string, scopes ...string) Option
- func SecurityScheme(name string, options ...swagger.SecuritySchemeOption) Option
- func Tag(name, description string, options ...TagOption) Option
- func TermsOfService(v string) Option
- func Title(v string) Option
- func Version(v string) Option
- type TagOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Option ¶
type Option func(builder *Builder)
Option provides configuration options to the swagger api builder
func SecurityScheme ¶
func SecurityScheme(name string, options ...swagger.SecuritySchemeOption) Option
SecurityScheme creates a new security definition for the API.
type TagOption ¶
TagOption provides additional customizations to the #Tag option
func TagDescription ¶
TagDescription sets externalDocs.description on the tag field
Source Files
Directories