go-swagger/go-swagger

Swagger 2.0 implementation for go

Swagger 2.0

---

This project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0). It provide tools to work with swagger specifications.

Swagger is a simple yet powerful representation of your RESTful API.

Documentation

https://goswagger.io

Features

go-swagger brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API: server, client and data model.

• Generates a server from a swagger specification
• Generates a client from a swagger specification
• Generates a CLI (command line tool) from a swagger specification (alpha stage)
• Supports most features offered by jsonschema and swagger, including polymorphism
• Generates a swagger specification from annotated go code
• Additional tools to work with a swagger spec
• Great customization features, with vendor extensions and customizable templates

Our focus with code generation is to produce idiomatic, fast go code, which plays nice with golint, go vet etc.

More details.

Project status

This project supports OpenAPI 2.0. At this moment it does not support OpenAPI 3.x.

go-swagger is now feature complete and has stabilized its API.

Most features and building blocks are now in a stable state, with a rich set of CI tests.

The go-openapi community actively continues bringing fixes and enhancements to this code base.

There is still much room for improvement: contributors and PR's are welcome. You may also get in touch with maintainers on our slack channel.

Installing

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

go-swagger is also available as binary or docker releases as well as from source: more details.

Try it

Try go-swagger in a free online workspace using Gitpod:

Licensing

The toolkit itself is licensed under an Apache Software License 2.0.

Just like swagger, this does not cover code generated by the toolkit. That code is entirely yours to license however you see fit.

Licence scan on dependencies

go-swagger's Issues

Go-swagger validation issues

There are 3 issues that I found.

For the test swagger file, you can download from: https://github.com/lixingwang/go-swagger-files/blob/master/SwaggerValidationIssues.json

1. Validation error while define parameter with more than one ref fields(line 319).
   
2. Validate Error while define response definition and including 'examples' element(line 847)

3. Validate Error while define parameter definition and including path parameter element(line 30 and line 804)

They should valid swagger file but go-swagger validator treat it as invalid.

validation: referenced objects

each reference must point to a valid object (Error)

import package issue

The generated code is still referring to casualjim repository:

   "github.com/casualjim/go-swagger"
    "github.com/casualjim/go-swagger/middleware"
    "github.com/casualjim/go-swagger/spec"
    "github.com/casualjim/go-swagger/strfmt"

Moreover, the middleware package is actually under github.com/casualjim/go-swagger/middleware/httpkit/middleware.

In some other imports there is a reference to validation package

"github.com/casualjim/go-swagger/validation"

I guess that it should refer to validate package?

Could you please point me to the right place in the code so I can update it. I would be happy to contribute and help.

may be bug on URI parse

I follow the homepage of the project,

swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json

but have error:

The swagger spec at "https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json" is invalid against swagger specification 2.0. see errors :
- host in body must be of type uri: "petstore.swagger.io"

follow the code, may be something wrong when call function

func IsStrictURI(str string) bool {
    _, err := url.ParseRequestURI(str)
    return err == nil
}
github.com/go-swagger/go-swagger/strfmt/default.go

the params pass to IsStrictURI is petstore.swagger.io

is that should be http://petstore.swagger.io or https://petstore.swagger.io ?

Generated configure_{app}.go has missing import and invalid reference

The generated code is missing the httpkit import:

import "github.com/go-swagger/go-swagger/httpkit"

and the following code should refer to httpkit and not swagger

api.JSONConsumer = swagger.JSONConsumer()
api.JSONProducer = swagger.JSONProducer()

should be:

api.JSONConsumer = httpkit.JSONConsumer()
api.JSONProducer = httpkit.JSONProducer()

Good thing about this is it's not regenerated when swagger generate is executed again so it's easy fix.

[validation] incorrect validation of path parameters defined in /parameters

The following Swagger 2.0 spec is valid but swagger validate reports a false negative:

The swagger spec at "global-parameters.json" is invalid against swagger specification 2.0. see errors :
- path param "userId" is not present in the path

Parameter userId is not used in any path (there is no parameters section for path / with a $ref to /parameters/userId). This should not be reported as an error.

{
  "swagger": "2.0",
  "info": {
    "version": "0.0.1",
    "title": "test of Swagger global parameters"
  },
  "parameters": {
    "userId": {
      "name": "userId",
      "in": "path",
      "type": "string",
      "required": true
    }
  },
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "Successful"
          }
        }
      }
    }
  }
}

models composed with discriminators and allOf end up with empty bodies

I tried generating a server using the models from the Models with Polymorphism Support example, which uses Pet as a parent interface for Cat and Dog. Both Cat and Dog contain properties inherited from Pet, as well as their own unique properties. The models for Cat and Dog seem to be empty structs (type Cat struct {}). Is that expected?

support huge file uploads

Currently the client uses a buffer to build a request.

It needs to use a io.Pipe and a goroutine to defer reading the file and writing it to the connection.

make generate spec support validations for nested collections

Currently the syntax for generating specs from go code has no notion of nested collections like [][][]string

There should be syntax for this.

perhaps:
there is a number of > signs in front of items which indicates to which level of the nesting the validation applies.

packages order

I used the petstore example provided in (https://github.com/go-swagger/go-swagger/tree/master/examples) to test the server generation.
The generated code differs from the one existing in the example folder where the generated code is composed of 3 packages:

• cmd
• models
• restapi
  • operations
    • pet
    • store
      • user

my generated code is:

• cmd
• models
• restapi
  • operations
• operations
  • restapi
    • pet
    • store
    • user

I think that somewhere in the code generation there is an "operations/restapi" instead of "restapi/operations".

/cc @maximilien

running on google app engine

App engine apps use some package imports which don't resolve when run with go build: "appengine", "appengine/datastore", etc. But it seems like "swagger generate spec" fails if it can't first build my app. To support app engine you'd need to remove that requirement. I would like to use go-swagger with my app engine project, so please make it parse the comments without first needing to build the app.

validation: unique scopes in security definitions

each security scope in a security definition should be unique

At the top level of the swagger object there is a property SecurityDefinitions: https://github.com/go-swagger/go-swagger/blob/master/spec/swagger.go#L48
This object is a map https://github.com/go-swagger/go-swagger/blob/master/spec/swagger.go#L169-L170

The value of that property is a map, to resolve this issue you can't work with the actual swagger object.
You have to work with the map that's obtained by parsing the raw byte value of the spec to a map[string]interface{}

The way the object model is set up is that it uses a map, by definition keys are unique in a map, so once parsed into the swagger object model this error would be lost.

you have to look into securityDefintions[key].scopes for unique values. The values only have to be unique within a particular key.

implement validation: unique scopes in security reference

each security reference should contain only unique scopes (Warning)

Is there a way to set the "reason" or "response model" fields for a response?

I could not find a way to put a message or structure next to each response for an api route. In swagger-ui the response area just lists the response codes, but no description next to them. Is there a way to populate these fields using code comments (with generate spec)?

go install undefined

when i exec

go get -u github.com/casualjim/go-swagger/cmd/swagger

i get
../../scan/schema.go:483: scp.program.Package undefined (type *loader.Program has no field or method Package)

Move all the packages to their proper homes

This repo will get split up into several packages and repos under the go-swagger org.

The transformation will be as follows:

Assets and spec json files should move into the spec package and perhaps just embedded as strings.

move casualjim/go-swagger/spec => go-swagger/swagger
move casualjim/go-swagger/swag => go-swagger/swag
move casualjim/go-swagger/httpkit => go-swagger/httpkit
move casualjim/go-swagger/cmd => go-swagger/tool and turn into a go workspace with vendoring.
move casualjim/go-swagger/docs => go-swagger/go-swagger.github.io

Validation:"swagger" field must validate against schema

When missing "swagger" field, the validation passed. But the "swagger" field is required in schema， so it should validate against schema.

BTY, there are three required filed "swagger", "info" and "paths", but the validation result is different.

1. Missing "swagger" field, validation pass.
2. Missing "info", validation failure failed, get error message ".info in body is required".
3. Missing "paths", get "nil pointer dereference" error, the related issue #52.

So hope the 1 and 3 could be fixed.

support websocket schemes

The client should be able to use websocket (ws:// and wss://) as scheme in addition to http:// and https://

try to make use of the rest of the swagger eco system

For the established tools perhaps do some path lookups and see if these things are on the path and list them as valid sub commands in the swagger command.

This could be extended with an install command so that there is a single entry point to work with swagger.

obvious candidates:

• swagger editor
• swagger ui
• swagger codegen

generate spec doesn't add "swagger":2.0 at the beginning of the spec, but it's needed by swagger-ui

When trying to run swagger-ui with a swagger.json generated from your included petstore example, swagger-ui errors out with TypeError: spec is null

I compared the generated spec with the offical petstore swagger.json, and noticed "swagger":2.0 was missing from the beginning of the generated one, and after manually adding it, the generated spec then worked with swagger-ui.

Please fix the generator so that generated specs work with swagger-ui.

Validation failed for json swagger if the response schema defined type=array

Defined a response, in it the schema specify array type. The validation failed with message "response body for 'operationxx' is a collection without an element type"

...
"responses": { 
             "200": {
                        "description": "Successful operation",
                        "schema": {
                            "type": "array",
                            "$ref": "#/definitions/DeleteResponse"
                        }
                    }
             }
....

generate spec doesn't fill in the description field for responses, which is required.

I tried a few kinds of comments and none of them got the description filled:

// swagger:response photoResponse [description here]
This one caused the response to not get added to the generated spec at all.

// swagger:response photoResponse
//
// [description here]
This one did not get the description filled in, but the response was added to the spec.

// [description here]
// swagger:response photoResponse
This one got the description filled as the "title" field for that particular object, but not as a description for the response.

Array references are generated as array of structs rather than array of pointers.

Example definition:

OrderPlacement:                                                                      
  properties:                                                                        
    items:                                                                           
      type: 'array'                                                                  
      items: { '$ref': '#/definitions/OrderItem' }

The generated server code looks like this:

// OrderPlacement                                                                      
type OrderPlacement struct {                                                           

  // Items                                                                             
  Items []OrderItem `json:"items" xml:"items"`                                         
}                                                                                      

Note the []OrderItem. Per de facto Go conventions I think this should be []*OrderItem.

Support password extended string format

You have pretty much everything but the one thing that is needed, password here: https://github.com/casualjim/go-swagger#whats-inside

Security names are mangled in generated `AuthenticatorsFor` method.

Relevant part from my current swagger.yaml:

securityDefinitions:  
  api_key:            
    type: "apiKey"    
    name: "api_key"   
    in: "query"       
security:             
  - "api_key": []     

And here is the generated AuthenticatorsFor method in the main API interface file:

// AuthenticatorsFor gets the authenticators for the specified security schemes                                                     
func (t *TixGenAPI) AuthenticatorsFor(schemes map[string]spec.SecurityScheme) map[string]httpkit.Authenticator {                                                                                           
  result := make(map[string]httpkit.Authenticator)                                         
  for name, scheme := range schemes {                                                      
    switch name {                                                                          

    case "apiKey":                                                                         

      result[name] = security.APIKeyAuth(scheme.Name, scheme.In, func(tok string) (interface{}, error) { return t.APIKeyAuth(tok) })

    }                                                                                      
  }                                                                                        
  return result                                                                            

}                                                                                          

However if I add fmt.Println(name) to the loop, only api_key is printed. So authenticators will never match. I think this is related to the security definition names being mangled at

go-swagger/generator/support.go

Line 345 in 0030e4a

Name: swag.ToJSONName(req.Name),

.

If i change the referenced line to remove swag.ToJSON (don't touch the name), everything works correctly.

But I am not sure if that is the correct fix.

Struct references in operation parameter objects are generated as struct fields instead of pointers.

Spec:

'/order':                                                                                
  post:                                                                                  
    tags: ['order']                                                                      
    operationId: 'postOrder'                                                             
    summary: 'Creates a new Order.'                                                      
    parameters:                                                                          
      - name: 'order'                                                                    
        in: 'body'                                                                       
        required: true                                                                   
        schema: { '$ref': '#/definitions/OrderPlacement' }                               

Generated handler looks like this:

// PostOrderHandlerFunc turns a function with the right signature into a post order handler
type PostOrderHandlerFunc func(PostOrderParams, *models.Principal) (*models.Result, error) 

func (fn PostOrderHandlerFunc) Handle(params PostOrderParams, principal *models.Principal) (*models.Result, error) {
  return fn(params, principal)                                                             
}

And the generated parameter object looks like this:

// PostOrderParams contains all the bound params for the post order operation       
// typically these are obtained from a http.Request                                 
type PostOrderParams struct {                                                       
  // info about the order to place, along with payment authorization token.         
  Order models.OrderPlacement                                                       
}

I think either:

• The Order field should be a pointer or...
• The PostOrderParams in the handler signature should be a pointer.

scanner.go panics with index out of bounds

scanner.go panics with index out of bounds when the lines it's looking at are empty.
it should not panic and bail if this is the case

Generated fields with `format: "date-time"` have invalid validation code.

Test repo: https://github.com/chakrit/go-swagger-issues/tree/master/date-time-validator . Clone it and run:

$ cd date-time-validator
$ ./test.sh

The gist of the issue is that validators for properties that is defined as { type: "string", format: "date-time" } gets invalid validation code generated.

Interestingly if required: ['created_at'] line is removed from the spec, no validations is generated and thus the generated code would compiles successfully.

Basic usage of 'swagger generate spec'

Hi,

I tried to generate a swagger.json file with some annotations in my Go code but I do not find any concrete examples and I have always this result

> swagger generate spec -o ./swagger.json
{"swagger":"2.0","paths":null}

I tried those annotations from this document but it is not working properly or I do not know how to use them.

http://godoc.org/github.com/go-swagger/go-swagger/scan

Does an exemple of swagger generate spec exist ?

validation: referencable references

each referencable definition must have references (Warning)

Generated imports for models are incorrect

When using swagger generate server -f swagger.yml -A myApp, the imports for the model in the code inside restapi/operations are incorrect.

The import statement looks like this:

import (
    "net/http"

    "github.com/myRepo/myApp/operations/models"
    "github.com/go-swagger/go-swagger/httpkit/middleware"
)

The models are in github.com/myRepo/myApp/models and not in github.com/myRepo/myApp/operations/models.

This causes compile errors.

Generated Go code fails to transform multiline descriptions

I have a sample description of an API

{
    "swagger": "2.0",
 ...
                "description": "Checks for VM presence.\n",
                "parameters": [
                    {
                        "name": "vm_cid",
                        "in": "query",
                        "description": "cloud ID of the VM created disk will most likely be attached; \nit could be used to optimize disk placement so that disk is located near the VM\n",
                        "required": true,
                        "type": "string"
  ...
}

The generated code fails to compile because the "description" element is transformed to multiple lines where the comment covers just the first line.
Here is the code for parameters.go:

type Params struct {
  // cloud ID of the VM created disk will most likely be attached; 
it could be used to optimize disk placement so that disk is located near the VM
  VMCid string
}

It seems that the "\n" in the description is causing this issue and when I removed it the generation went through. I tried to resolve the issue but unfortunately I didn't find the right code to modify. Any hints to help?
/cc @maximilien

`strfmt` types should implement database marshaling methods.

Personally I think this should be a package separate from go-swagger. Validations and creations of the value types implemented here could be re-used in a lot of other projects.

My issue however, is to request that the values implement basic sql.Scanner and database/sql/driver.Valuer so that text-based types such as strfmt.Email and strfmt.UUID on the structs can be marshalled to-and-fro the database without having to define a new type.

The implementation is quite trivial since most string types are just straight type renames so the implementation of those interfaces is just converting them back to the base string type.

Here's an example of how I define a UUID type (before go-swagger):

type ID string                                                 

var __id = ID("asdf")                                          
var _ sql.Scanner = &__id                                      
var _ driver.Valuer = __id                                     

func NewID() ID {                                              
  raw := uuid.NewV4().String()                                 
  raw = raw[1 : len(raw)-1]                                    
  raw = strings.ToLower(raw)                                   
  return ID(raw)                                               
}                                                              

func (id *ID) Scan(raw interface{}) error {                    
  switch v := raw.(type) {                                     
  case []byte:                                                 
    *id = ID(string(v))                                        
  case string:                                                 
    *id = ID(v)                                                
  default:                                                     
    fmt.Errorf("cannot sql.Scanner.Scan() to `ID` from: %#v", v)
  }                                                            

  return nil                                                   
}                                                              

func (id ID) Value() (driver.Value, error) {                   
  return driver.Value(string(id)), nil                         
}                                                              

As you can see, pretty trivial conversion. With this I can use this type inside any structs type User struct{ id ID } and all it'd marshal to-and-fro the db without a hitch.

This is esp. important when using go-swagger with jmoiron/sqlx or any database mapping library in general.

Add support for request tracing

Allow to set one or more header params that will be included in every client request / server handler and made available for consumer code.

This process can be made largely transparent this is hugely useful for building up journals of the path a request took through a distributed system.

The default implementation should be simple and is a simple key: uuid.
This should be an interface so that more elaborate hashing schemes can be provided.

Request tracing can also be used for flight assignment in A/B type scenarios.

Create stub data generator (auto serve stub api with just a spec)

create a data generator that uses an extension property: x-gen-type

This property takes a string which is the data generator for that particular type.

for example for a person there might be the following extras:

definitions:
  Person:
    properties:
      firstName:
        type: string
        x-gen-type: firstname
      lastName:
        type: string
        x-gen-type: lastname
      age:
        type: number
        format: int32
        x-gen-type: range:10-50
      createdAt:
        type: string
        format: date-time
        x-gen-type: now

there are certain generators that will need to take arguments. The syntax above is just a proposal, welcoming suggestions.

The idea is that you can serve a swagger spec to test clients against, and it will know how to generate meaningful data.
So that when you have a backend team implementing a new application, the frontend team can already work with the stubbed out data. The application should still look kind of acceptable.
Of course for blurbs of text there is lorem ipsum and so on.

This can be made more useful for testing when it's combined with fuzzer.

Generate a swagger spec from go code

Generate a swagger spec from go code:

• generate schema objects for models
• generate api info from comments, presumably the main godoc for the package
• generate path objects from operation annotation
• generate security definitions from security annotations

generate spec should remove request body params with the `json:"-"` tag

Instead these fields are given the key "-", which is not correct behaviour. json:"-" is supposed to be a way to remove a struct field from the json representation of that struct, as such that needs to be honoured in the generated swagger spec.

implement validation: duplicate property name declaration

definition can't declare a property that's already defined by one of its ancestors (Error)

This is for definitions with an allOf property.

Nil pointer dereference exception while validate an swagger without path

I want to use go-swagger validation feature so I defined an very simple swagger without paths, see the swagger file:

"swagger" : "2.0",
  "info" : {
    "version" : "1.0",
    "title" : "Hello World",
    "description" : "Simple Hello World API, with Get operation to one resource path, no request parameters defined"
  },
  "host" : "api.tibco.com",
  "basePath" : "/v1",
  "schemes" : [ "http" ]
}

Then it throw nil point exception, we hope it might return error with "Invalid swagger content, please provide paths....."

Hope this can be fixs.

Thanks,
Tracy

Please export common embedded structs as public

Some structs like simpleSchema should be exported.

Example usecase: (pseudo code)

func setType(p spec.SimpleSchema, t SourceType) {
    if t.IsRef() {
        p.Ref = spec.MustCreateRef("#/definitions/" + t.GetName())
    } else {
        p.Type = toSwaggerType(t)
        p.Format = toSwaggerFormat(t)
    }
}

Add support for the password format

Add support for the password format.
This should be like the url string format, mostly a place holder and marker.
There will be no validation specified, this should come from the pattern etc property.

Support for JSON schema cross-file references.

AFAIK This is valid JSON schema references:

definitions: { '$ref': 'another-file.json#/definitions' }

This should be supported in go-swagger. Not sure how much effort is needed tho. This allows multiple schema to share definitions or for splitting large schema into smaller files, for example.

Ability to generate `all` operations but not the model.

Right now the --name flag when doing swagger generate operation is mandatory. I think it should not be. It is currently impossible to generate all operations in the swagger file but skip out the models, for example. You either have to know the name of all the operations or you have to generate the entire server package and pick out what you want.

implement validation: circular ancestry

definition's ancestor can't be a descendant of the same model (Error)

this applies again to allOf models

bind{Param} function may need casting for UUID

compiling a generated server with path parameters defined as type: string and format: uuid throws this error: cannot use raw (type string) as type strfmt.UUID in assignment

The raw parameter for bind{Param}() function may need to be casted strfmt.UUID (or any other custom types defined?).

make generated server support responses

Currently the generated server assumes that responses never define headers.

validation: default values must validate against schema

every default value that is specified must validate against the schema for that property (Error)

Response schema with `type: any` result in pointer-to-interface.

Relevant section:

paths:                                                      
  '/_debug':                                                
    get:                                                    
      tags: ['debug']                                       
      operationId: 'getDebug'                               
      summary: 'Debug route strictly for testing.'          
      responses:                                            
        '200':                                              
          descrition: 'Debug result.'                       
          schema: { type: 'any' }                           

Produces the following type:

type GetDebugHandlerFunc func(*models.User) (*interface{}, error)                   

func (fn GetDebugHandlerFunc) Handle(principal *models.User) (*interface{}, error) {
  return fn(principal)                                                              
}

Notice the *interface{} there. I think this should be plain non-pointer interface{} ?

documentation site

Documentation site

This site should explain what swagger is. It should also explain why swagger is important.
It links to the swagger spec document (might import it to fit within the theme of the site)

I think the best approach is to explain 3 different POV's when developing apis. The website should explain how this is a toolkit and not a framework, and how people can take it as far as they want (mix and match).

Different POV's:

• Design First (the swagger spec is the source of truth)
• Develop First (the code is the source of truth)
• Hybrid (uses design first or develop first depending on the situation)

Phase 1: greenfield app, design discussion produces a swagger spec which needs to serve a stub api asap.
Phase 2: stubs get replaced by actual functionality, some models need to be adjusted. This should be able to keep the spec in sync with the code written.

[validation] pathItems properties are not strictly validated

This spec is invalid (invalid-property is not allowed in a pathItem) but go-swagger accepts it:

{
  "swagger": "2.0",
  "info": {
    "version": "0.0.1",
    "title": "test of Swagger of additionalProperties in pathItem"
  },
  "paths": {
    "/": {
      "invalid-property": null
    }
  }
}

Only vendor extensions (properties starting with x- should be accepted in addition to the normalized properties. See /definitions/pathItem in the JSON schema for Swagger 2.0.