Go Swagger Generator is a tool to parse Golang source files and generate Swagger json.
Tool is based on go-swagger and supports everything that go-swagger supports, but allows to define responses and parameters as yaml.
Go-swagger expects separate structure for every response, but in my case we generate it dynamically in controller.
// swagger:route PUT /packages/{id} Package packagePut // // Update package // // Parameters: // id string in:path required "Package ID" // content PutPackage in:body required "Update package params" // | - name: type // | in: query // | description: Example parameter defined as yaml // | required: true // | type: string // | enum: // | - value1 // | - value2 // // Responses: // 200: "OK" // | schema: // | properties: // | data: // | $ref: "#/definitions/PackageGet" // | meta: // | $ref: "#/definitions/Meta" // 404: "Package not found" // | schema: // | $ref: "#/definitions/ErrorResponse" // 422: "422 Unprocessable Entity" // | schema: // | $ref: "#/definitions/ErrorResponse" func PackagePut() http.HandlerFunc { ... }go-swagger-gen spec -m -i third_party_swagger.json -b project/cmd/http -o swagger.json --compact
Usage: go-swagger-gen [OPTIONS] spec [spec-OPTIONS] generate spec file from go code Help Options: -h, --help Show this help message [spec command options] -b, --base-path= the base path to use (default: .) -m, --scan-models includes models that were annotated with 'swagger:model' --compact when present, doesn't prettify the the json -o, --output= the file to write to -i, --input= the file to use as input Please refer to go-swagger documentation, swagger.json section.
Allows to define route params in short form:
// swagger:route ... // // Parameters: // <name> <type> in:<place> <is-required> "<description>" Where:
name- parameter nametype- any go type or struct withswagger:modelannotationplace- path/query/header/body/formDatais-required- true/false or required (works as true)
// swagger:route ... // // Parameters: // | valid swagger parameters yaml as array Just put here normal swagger yaml, but prepend it with | symbol.
// swagger:route ... // // Responses: // <code>: "<description>" // | valid swagger response yaml Where:
code- integer response codedescription- response description
Just put here normal swagger yaml, but prepend it with | symbol.
type MyModelResponseDTO struct { // format: date-time CreatedAt string `json:"created_at"` }type MyModelInputDTO struct { CreatedAt time.Time `json:"created_at"` }type MyModelInputDTO struct { //don't need to add "required" comment CreatedAt time.Time `json:"created_at" valid:"required"` }type MyModelInputDTO struct { //technical comment, shouldn't appear as description in swagger // but this comment is used as description CreatedAt time.Time `json:"created_at" valid:"required"` }type Int64 int64 type MyModel struct { // min: 10 IntField Int64 `json:"intField"` }Aliases in swagger.json present as native types. Therefore all validation comments work as expected for them.
(similar fix was merged to go-swagger go-swagger/go-swagger#1087, but works slightly different)
I don't want to expose internal name in swagger
Scanner creates swagger definitions for embedded structures too, but often we don't need them.
Consider example:
type BaseModel struct { ... } // swagger:model type MyModel struct { BaseModel ... } // we use only "#/definitions/MyModel" somewhere // but BaseModel definition will also appear in swagger jsonTherefore go-swagger-gen analyzes final json and removes unused definitions.