Swagger 2.0 implementation for go

Overview

Swagger 2.0 Build Status Build status codecov GitHub version

Slack Status license GoDoc Docker Repository on Quay FOSSA Status GolangCI Go Report Card

This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.

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

swagger Swagger in a nutshell

With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment.

With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. We created Swagger to help fulfill the promise of APIs.

Swagger helps companies like Apigee, Getty Images, Intuit, LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the best possible services with RESTful APIs. Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software.

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
  • 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.

Project status

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.

Documentation

https://goswagger.io

FAQ

Q&A contributed by the community:

https://goswagger.io/faq/

How is this different from go generator in swagger-codegen?

tl;dr The main difference at this moment is that this one actually works...

The swagger-codegen project only generates a workable go client and even there it will only support flat models. Further, the go server generated by swagger-codegen is mostly a stub.

Motivation Why is this not done as a part of the swagger-codegen project? Because:

  • I don't really know java very well and so I'd be learning both java and the object model of the codegen which was in heavy flux as opposed to doing go and I really wanted to go experience of designing a large codebase with it.
  • Go's super limited type system makes it so that it doesn't fit well in the model of swagger-codegen
  • Go's idea of polymorphism doesn't reconcile very well with a solution designed for languages that actually have inheritance and so forth.
  • For supporting types like [][][]map[string][][]int64 I don't think it's possible with mustache

I gravely underestimated the amount of work that would be involved in making something useful out of it. My personal mission: I want the jvm to go away, it was great way back when now it's just silly (vm in container on vm in vm in container)

What's inside?

Here is an outline of available features (see the full list here):

  • An object model that serializes swagger-compliant yaml or json
  • A tool to work with swagger
    • Serve swagger UI for any swagger spec file
    • Flexible code generation, with customizable templates
      • Generate go API server based on swagger spec
      • Generate go API client from a swagger spec
    • Validate a swagger spec document, with extra rules outlined here
    • Generate a spec document based on annotated code
  • A runtime to work with Rest API and middlewares
    • Serve spec
    • Routing
    • Validation
    • Authorization
    • Swagger docs UI
    • A Diff tool which will cause a build to fail if a change in the spec breaks backwards compatibility

There is more to that...

  • A typed JSON Schema implementation, supporting most Draft 4 features
  • Extended string and numeric formats: strfmt
  • Utilities to work with JSON, convert data types and pointers: swag
  • A jsonschema (Draft 4) validator, with full $ref support: validate
  • Custom validation interface

Installing

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

Use-cases

The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger.

The toolkit is highly customizable and allows endless possibilities to work with OpenAPI2.0 specifications.

Beside the go-swagger CLI tool and generator, the go-openapi packages provide modular functionality to build custom solutions on top of OpenAPI.

The CLI supports shell autocompletion utilities: see here.

Serve specification UI

Most basic use-case: serve a UI for your spec:

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

Validate a specification

To validate a Swagger specification:

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

Generate an API server

To generate a server for a swagger spec document:

swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]]

Generate an API client

To generate a client for a swagger spec document:

swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]]

Generate a spec from source

To generate a swagger spec document for a go application:

swagger generate spec -o ./swagger.json

Generate a data model

To generate model structures and validators exposed by the API:

swagger generate model --spec={spec}

Transform specs

There are several commands allowing you to transform your spec.

Resolve and expand $ref's in your spec as inline definitions:

swagger expand {spec}

Flatten your spec: all external $ref's are imported into the main document and inline schemas reorganized as definitions.

swagger flatten {spec}

Merge specifications (composition):

swagger mixin {spec1} {spec2}

Compare specs

The diff command allows you to check backwards compatibility. Type swagger diff --help for info.

swagger diff {spec1} {spec2}

Generate spec markdown spec

swagger generate markdown -f {spec} --output swagger.mode

Try it

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

Open in Gitpod

Licensing

The toolkit itself is licensed as 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.

FOSSA Status

Who is using this project?

To name but a few... (feel free to sign in there if you are using this project):

In the list below, we tried to figure out the public repos where you'll find examples on how to use go-swagger and go-openapi:

3DSIM
Alibaba PouchAPI
CheckR
Cilium
CoreOS
NetBox Community
EVE Central
Iron.io JaegerTracing
Kubernetes-Helm
Kubernetes
ManifoldCo
Metaparticle.io
Netlify
Nutanix
OAS2
OVH API
RackHD
ScaleFT
StratoScale
Terraform Provider OpenAPI
VMware
...

Note to users migrating from older releases

Migrating from 0.25 to [master]

Changes in the behavior of the generated client regarding defaults in parameters and response headers:

  • default values for parameters are no more hydrated by default and sent over the wire (assuming the server uses defaults).
  • the previous behavior (explicitly sending defaults over the wire) can be obtained with the SetDefaults() and WithDefaults() parameter methods.
  • the body parameter is not pre-hydrated with the default from it schema
  • default values for response headers are hydrated when the header is not received (previously, headers remained with their zero value)

Migrating from 0.24 to 0.25

The options for generate model --all-definitions and --skip-struct are marked for deprecation.

For now, the CLI continues to accept these options. They will be removed in a future version.

Generating all definitions is now the default behavior when no other option filters the generation scope. The --skip-struct option had no effect.

Migrating from 0.14 to 0.15

Generated servers no more import the following package (replaced by go1.8 native functionality):

github.com/tylerb/graceful

Spec flattening now defaults to minimal changes to models and should be workable for 0.12 users.

Users who prefer to stick to 0.13 and 0.14 default flattening mode may now use the --with-flatten=full option.

Note that the --skip-flatten option has been phased out and replaced by the more explicit --with-expand option.

Migrating from 0.12 to 0.13

Spec flattening and $ref resolution brought breaking changes in model generation, since all complex things generate their own definitions.

Migrating from 0.5.0 to 0.6.0

You will have to rename some imports:

github.com/go-swagger/go-swagger/httpkit/validate to github.com/go-openapi/validate
github.com/go-swagger/go-swagger/httpkit to github.com/go-openapi/runtime
github.com/naoina/denco to github.com/go-openapi/runtime/middleware/denco
github.com/go-swagger/go-swagger to github.com/go-openapi

Using 0.5.0

Because 0.5.0 and master have diverged significantly, you should checkout the tag 0.5.0 for go-swagger when you use the currently released version.

Comments
  • responses with external $ref thrown nil pointer dereference

    responses with external $ref thrown nil pointer dereference

    Problem statement

    Using an external $ref definition for responses thrown nil pointer dereference:

    panic: runtime error: invalid memory address or nil pointer dereference
    [signal SIGSEGV: segmentation violation code=0x1 addr=0x10 pc=0x8bf5f0]
    
    goroutine 1 [running]:
    github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate.(*SpecValidator).validateResponseExample(0xc421d27c80, 0xc4202b34c8, 0x1, 0xc421d27818, 0xc42008c780)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate/spec.go:837 +0x3d0
    github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate.(*SpecValidator).validateExamplesValidAgainstSchema(0xc421d27c80, 0xc421d27a90)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate/spec.go:876 +0x281
    github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate.(*SpecValidator).Validate(0xc421d27c80, 0xb610e0, 0xc4202a4690, 0x0, 0x0)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/vendor/github.com/go-openapi/validate/spec.go:161 +0x4bb
    github.com/go-swagger/go-swagger/cmd/swagger/commands.(*ValidateSpec).Execute(0xc4202b2608, 0xc4200e7d00, 0x1, 0x2, 0xc4202b2608, 0x1)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/cmd/swagger/commands/validate.go:60 +0x168
    github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags.(*Parser).ParseArgs(0xc420159320, 0xc420010190, 0x2, 0x2, 0x412608, 0xc420490630, 0xc42018fe00, 0xc4200e7201, 0xc420257d40)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags/parser.go:316 +0x841
    github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags.(*Parser).Parse(0xc420159320, 0x6, 0xbb0ebe, 0x6, 0x0, 0xbf88d9)
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags/parser.go:186 +0x71
    main.main()
    	/home/hello/workspace/project/go/src/github.com/go-swagger/go-swagger/cmd/swagger/swagger.go:140 +0xd89
    

    Swagger specification

    responses.yaml:

    swagger: '2.0'
    info:
      title: Responses
      version: 0.1.0
    responses:
      NotFound:
        description: Not found
    
    paths:
      /:
        get:
          summary: GET
          operationId: getAll
          responses:
            '200':
              description: Ok
    

    swagger.yaml:

    swagger: '2.0'
    info:
      title: Object
      version: 0.1.0
    
    paths:
      /:
        get:
          summary: GET
          operationId: getAll
          responses:
            '200':
              description: Ok
            '404':
              $ref: './responses.yaml#/responses/NotFound'
    
    

    Steps to reproduce

    swagger validate swagger.yaml
    

    Environment

    swagger version: tested with 0.13.0 and dev go version: 1.9.2 OS: Ubuntu 16.04

    bug in progress Ref resolution validate spec 
    opened by BertrandGouny 30
  • Stack overflow error in swagger validate

    Stack overflow error in swagger validate

    When running swagger validate ./public/swagger.v1.json probably after #1608 was merged we are having error:

    runtime: goroutine stack exceeds 1000000000-byte limit
    fatal error: stack overflow
    

    For more details see: https://drone.gitea.io/go-gitea/gitea/1918/8

    bug validate spec pending PR 
    opened by lafriks 29
  • embedded spec discards information from original spec

    embedded spec discards information from original spec

    Problem statement

    Given this spec

    swagger: '2.0'
    consumes:
      - application/json
    produces:
      - application/json
    info:
      title: Test
      version: 1.0.0
    securityDefinitions:
      keystone:
        type: apiKey
        in: header
        name: x-auth-token
    security:
      - keystone: []
    paths:
      /info:
        get:
          security: []
          responses:
            '200':
              description: OK
              schema:
                type: string
    
    

    The embedded spec in the generated server is missing the security: [] entry in the operation. This is semantically different from the original spec where the global security setting is explicitly overridden to be empty (no authentication for this operation required).

    The problem is caused by an omitempty struct tag. I'll open a PR there to fix this issue.

    Steps to reproduce

    swagger generate server --name test --target test swagger.yaml

    Environment

    swagger version: 0.13.0
    go version: 1.9.2 OS: Darwin

    bug needs testing auth 
    opened by databus23 27
  • Support go modules

    Support go modules

    Supporting go modules will require a number of changes. Some are mechanical and can be scripted, others mean changing the way our code works.

    Tagging changes

    The first one is fairly easy. On the next release we tag versions with the v prefix. And we add a go.mod and go.sum file in every package under the go-openapi organization as well as in this go-swagger/go-swagger repository.

    • [x] Done

    Turn on go vet during tests

    Currently our generator package is doing a cute thing in the debugLog and debugLogAsJSON methods. go vet is unhappy about it, so we've turned it off until we can address the format string issues.

    https://github.com/search?l=&q=debugLog+repo%3Ago-swagger%2Fgo-swagger+extension%3Ago+path%3Agenerator&type=Code

    • [x] Done

    Package refactoring

    For our current version we don't need to rewrite packages or import paths, it's only if/once we decide to do v2 then we need to use different import paths.

    Generated code changes

    The generator should optionally add go.mod or edit the go.mod file with the required dependencies. Although the tooling should pick up on that too the first time the code gets run. But if people want to pin to older versions etc then this can help them out with that.

    Initial work has done some of this: https://github.com/search?q=%22go.mod%22+repo%3Ago-swagger%2Fgo-swagger+extension%3Ago+path%3Agenerator&type=Code

    Generator support

    We do lookups in the go path for guessing imports and so on. These will need to be made compatible with go modules. Currently we basically strip off or join with ${GOPATH-"$HOME/go"}/src

    We would need to change this logic to be aware of modules and look up with that tool.

    https://github.com/search?utf8=%E2%9C%93&q=GOPATH+repo%3Ago-swagger%2Fgo-swagger+extension%3Ago+extension%3Ago+path%3Agenerator%2F&type=Code&ref=advsearch&l=&l=

    Scanner support

    The scanner uses go/build from the go compiler infrastructure, to discover the files and packages that need to be introspected. This needs to move to the newer library: https://godoc.org/golang.org/x/tools/go/packages so that it's module aware.

    https://github.com/search?utf8=%E2%9C%93&q=GOPATH+repo%3Ago-swagger%2Fgo-swagger+extension%3Ago+path%3Ascan&type=Code&ref=advsearch&l=&l=

    related #1677

    enhancement go modules 
    opened by casualjim 26
  • Model definition not included when response definition has an external $ref containing a schema $ref

    Model definition not included when response definition has an external $ref containing a schema $ref

    Problem statement

    Not sure how to say that in a simple way, the example may be more relevant :) Model definition is not included when a response definition has an external $ref containing a schema with $ref.

    With swagger flatten the model definition is missing, swagger validate throw this error :

    some references could not be resolved in spec. First found: object has no key "Error"
    

    Steps to reproduce

    responses.yaml:

    swagger: '2.0'
    info:
      title: Responses
      version: 0.1.0
    definitions:
      Error:
        type: object
        description: |
          Contains all the properties any error response from the API will contain.
          Some properties are optional so might be empty most of the time
        required:
          - code
          - message
        properties:
          code:
            description: the error code, this is not necessarily the http status code
            type: integer
            format: int32
          message:
            description: a human readable version of the error
            type: string
          helpUrl:
            description: an optional url for getting more help about this error
            type: string
            format: uri
    
    responses:
      BadRequest:
        description: Bad request
        schema:
          $ref: '#/definitions/Error'
    
    paths:
      /:
        get:
          summary: GET
          operationId: getAll
          responses:
            200:
              description: Ok
    

    swagger.yaml

    swagger: '2.0'
    info:
      title: Object
      version: 0.1.0
    
    paths:
      /:
        get:
          summary: GET
          operationId: getAll
          responses:
            200:
              description: Ok
            400:
              $ref: './responses.yaml#/responses/BadRequest'
    

    Commands

    swagger validate swagger.yaml
    swagger flatten swagger.yaml
    

    Environment

    swagger version: dev + latest commit of github.com/go-openapi/validate

    bug Ref resolution spec pending PR 
    opened by BertrandGouny 24
  • generate spec for embedded struct: unknown primitive

    generate spec for embedded struct: unknown primitive

    The spec generate will often fail for me given the following definitions (for example)

    // ActionParam
    //
    // swagger:parameters actionParam
    type ActionParam struct {
        // in: body
        // required: true
        Body actionParam
    }
    
    type actionParam struct {
        // required: true
        FieldA string
    
        // required: true
        FieldB string
    
        // required: true
        FieldC int`
    }
    

    Generating a spec for this file will yield: unknown primitive "actionParam" Changing around all the fields, names, etc does not fix the issue.

    Currently on go 1.5.2 darwin/amd64 with the latest version of swagger.

    bug needs more info 
    opened by danfang 23
  • couldn't find a swagger spec

    couldn't find a swagger spec

    Problem statement

    Getting couldn't find a swagger spec when doing swagger generate server -A todo-list -f ./swagger.yml. I am following https://goswagger.io/tutorial/todo-list.html.

    Steps to reproduce

    1. Go to https://goswagger.io/tutorial/todo-list.html and copy the complete spec to a file called swagger.yml.
    2. Run swagger generate server -A todo-list -f ./swagger.yml from the directory of the file.

    Environment

    swagger version: version: v0.27.0 go version: go1.15.8 OS: Amazon Linux 2

    needs more info 
    opened by santosh 20
  • Generate spec does not work with Go Modules

    Generate spec does not work with Go Modules

    Problem statement

    the swagger CLI tool does not work correctly when the target repository is a Go 1.11 Module. The tool should not use GOPATH/src to resolve dependencies, and instead use the GOPATH/pkg/mod The possible failure cases I have discovered are as follows:

    1. required dependency is not in GOPATH
      1. results in the CLI tool saying it cannot find dependency
    2. dependency in GOPATH is not the same as declared in MODULE
      1. individual types/functions/packages fail, rather than the dependency as a whole
    generate spec go modules 
    opened by JeremyLoy 19
  • Client generation fails with `object has no key

    Client generation fails with `object has no key "UserBase"`

    Problem statement

    Client generation fails with object has no key "UserBase"

    Swagger specification

    2.0

    Steps to reproduce

    1. Create two files first.yml
    swagger: '2.0'
    
    info:
      version: '2.0'
      title: test
      description: test
      license:
        name: N/A
    
    basePath: /v2
    
    schemes:
      - http
      - https
    
    consumes:
      - application/json
    produces:
      - application/json
    
    paths:
      /user:
        get:
          operationId: getUser
          description: test
          responses:
            200:
              description: succes
              schema:
                $ref: 'second.yml#/definitions/User'
    
    

    /second.yml

    swagger: '2.0'
    
    info:
      version: '2.0'
      title: test
      description: test
      license:
        name: N/A
    
    basePath: /v2
    
    schemes:
      - http
      - https
    
    consumes:
      - application/json
    produces:
      - application/json
    
    definitions:
      UserBase:
        type: object
        properties:
          id:
            type: integer
            format: uint64
    
      User:
        allOf:
        - $ref: '#/definitions/UserBase'
        - properties:
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    
    1. run swagger generate client -f /Users/andrew/Workspace/go/src/github.com/go-swagger/example/first.yml -t /Users/andrew/Workspace/go/src/github.com/go-swagger/example/gen --skip-validation
    2. swagger returns object has no key "UserBase"

    Environment

    swagger version: latest from the master 220a68f31437616b53c032a5f82384450f82cf4e go version: go version go1.8.3 darwin/amd64 OS: MacOS Sierra 10.12.5

    bug Ref resolution spec 
    opened by andrewkavalionak 19
  • Quickly specify parameters under a route

    Quickly specify parameters under a route

    Problem statement

    I would like to specify parameters when creating a route, similar to Consumes, Produces, Responses, etc. These details are the first that come to mind, so it could probably use some iteration.

    // swagger:route PUT /profile/{id} update_profile
    //
    // Update a user profile
    //
    //     Parameters:
    //      - id: [in:path required:true type:string] Description goes here
    //      - profile: [in:body required:true model:profile_model]
    //     Consumes:
    //     - application/json
    //     Produces:
    //     - application/json
    //     Responses:
    //       200: ok
    //       404: NotFound
    

    In other places:

    // swagger:route GET /profile/{id} get_profile
    //
    // Get a user profile
    //
    //     Parameters:
    //      - id: [in:path required:true] Description goes here
    //     Consumes:
    //     - application/json
    //     Produces:
    //     - application/json
    //     Responses:
    //       200: profile_model
    
    // swagger:model profile_model
    type Profile struct {
        //a bunch of model info here
    }
    

    And this fits with #781, it would be nice to create a parameter and reuse it, so for example

    // swagger:parameter profile_id_param
    type ProfileIDParam struct {
        /*Profile id
          Required: true
          In: path
        */
        ID string `json:"id"`
    }
    

    and in the examples above, replace the lines that specify id with something like:

    // Parameters
    //  - predefined:profile_id_param
    
    duplicate wontfix 
    opened by clawconduce 18
  • Swager generate panic - commit #e2bfe4232707b33df6e46519f71f5d22cc6bf63b

    Swager generate panic - commit #e2bfe4232707b33df6e46519f71f5d22cc6bf63b

    Environment

    swagger version: commit #e2bfe4232707b33df6e46519f71f5d22cc6bf63b go version: 1.8.3 OS: OSX

    swagger generate server ./swagger.yaml

    2017/09/02 11:55:07 building a plan for generation
    2017/09/02 11:55:07 planning definitions
    panic: runtime error: invalid memory address or nil pointer dereference
    [signal SIGSEGV: segmentation violation code=0x1 addr=0xd pc=0x1567009]
    
    goroutine 1 [running]:
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).NewSliceBranch(0xc421c22000, 0xc421b88fc0, 0x1)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:387 +0x529
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).buildArray(0xc421c22000, 0x0, 0x0)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:1068 +0xe2
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).buildItems(0xc421c22000, 0x0, 0x0)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:1104 +0xc57
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).makeGenSchema(0xc421c22000, 0xc4210ac22c, 0x4)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:1445 +0xabc
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).buildProperties(0xc420155200, 0xc4201552a8, 0x100)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:660 +0x304
    github.com/go-swagger/go-swagger/generator.(*schemaGenContext).makeGenSchema(0xc420155200, 0x0, 0xc421f0bc50)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:1433 +0x9f3
    github.com/go-swagger/go-swagger/generator.makeGenDefinitionHierarchy(0xc4210c4e80, 0x7, 0xc421c9cf78, 0x6, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:166 +0x32c
    github.com/go-swagger/go-swagger/generator.makeGenDefinition(0xc4210c4e80, 0x7, 0xc421c9cf78, 0x6, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/model.go:133 +0xbc
    github.com/go-swagger/go-swagger/generator.(*appGenerator).makeCodegenApp(0xc42001e690, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/support.go:610 +0x5d9
    github.com/go-swagger/go-swagger/generator.(*appGenerator).Generate(0xc42001e690, 0x0, 0x0)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/support.go:262 +0x94
    github.com/go-swagger/go-swagger/generator.GenerateServer(0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xc4203a85a0, 0xc4206ef4b0, ...)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/generator/support.go:43 +0xcb
    github.com/go-swagger/go-swagger/cmd/swagger/commands/generate.(*Server).Execute(0xc420870840, 0xc4208678c0, 0x1, 0x3, 0xc420870840, 0x1)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/cmd/swagger/commands/generate/server.go:118 +0x54a
    github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags.(*Parser).ParseArgs(0xc42001c960, 0xc420010250, 0x3, 0x3, 0x1010f88, 0x30, 0xc420374870, 0xc42045d380, 0xc42045cd48)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags/parser.go:316 +0x893
    github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags.(*Parser).Parse(0xc42001c960, 0x6, 0x17aa779, 0x6, 0x0, 0x17f2a5c)
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/vendor/github.com/jessevdk/go-flags/parser.go:186 +0x73
    main.main()
    	/Users/krasimir/src/github.com/go-swagger/go-swagger/cmd/swagger/swagger.go:105 +0x858
    

    panics with the following swagger file.

    swagger: '2.0'
    info:
      version: 0.0.1
      title: User Management
    basePath: /v1/
    schemes:
      - http
    produces:
      - application/json
    consumes:
      - application/json
    security:
      - jwt: []
    
    paths:
      /user:
        get:
          summary: generates a list of users
          parameters:
            - in: query
              name: offset
              type: integer
              description: The number of items to skip before starting to collect the result set
            - in: query
              name: limit
              type: integer
              description: The numbers of items to return
          responses:
            200:
              description:  full user list
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                    username:
                      type: string
                    created:
                      type: string
                    f2a:
                      type: integer
            default:
              $ref: "#/responses/DefaultError"
      /user/login:
        post:
          security: []
          summary: generates a swt token to use for authentication
          parameters:
            - in: body
              name: body
              schema:
                  $ref: "#/definitions/Login"
    
          responses:
            200:
              description: A jwt token to use for authentication.
              schema:
                $ref: "#/definitions/Jwt"
            206:
              description: Account is with 2 factor authenticaiton so use the 2 factor endpoint to generate the final the jwt token.
              schema:
                $ref: "#/definitions/Jwt"
            201:
              description: Password change is required, hit the password reset endpoint with the generated jwt token
              schema:
                $ref: "#/definitions/Jwt"
            default:
              $ref: "#/responses/DefaultError"
      /user/2fa:
        delete:
          summary: disable 2 factor authenticaiton for an account
          parameters:
            - in: body
              name: body
              schema:
                $ref:
                  "#/definitions/F2aDisable"
          responses:
            200:
              description: 2fa disabled.
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        get:
          summary: generate qr base64 encoded image and master code for the user to scan with the google authenticator and add it to the phone app
          responses:
            200:
              description: A 2fa object.
              schema:
                properties:
                  qr:
                    type: string
                  secret:
                    type: string
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        put:
          summary: enables 2fa on an account
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/F2aEnable"
          responses:
            200:
              description: 2fa enabled.
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        post:
          summary: used when the account is with 2 factor authentication enabled. use the login endpoint first to get the initial jwt token and than use this endpoint to get the second jwt token after providing a valid google authenticator code
          security: []
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/F2aAuth"
          responses:
            200:
              description: the new jwt token that can be used for all endpoints.
              schema:
                $ref: "#/definitions/Jwt"
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
      /user/management:
        post:
          summary: creates a new user
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/Profile"
          responses:
            200:
              description: An user id of the created user.
              schema:
                type: object
                properties:
                  id_profile:
                    type: integer
            401:
              $ref: "#/responses/UnauthorizedError"
            409:
              $ref: "#/responses/UserExistsError"
            default:
              $ref: "#/responses/DefaultError"
        put:
          summary: updates an existing user, only submited fields will be updated so can ommit the ones that don't need updating
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/ProfileUpdate"
          responses:
            200:
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        delete:
          summary: deletes a user from the db
          parameters:
            - in: body
              name: body
              schema:
                type: object
                required:
                - id_profile
                properties:
                  id_profile:
                    type: integer
          responses:
            200:
              description: user deleted
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
    
      /user/password:
        post:
          summary: reset an user password, when old password is not provided the user will be required to change its password upon next login using a temporary password provided by an admin
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/PassReset"
          responses:
            200:
              description: "user updated"
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        put:
          summary: resets an user password using a temporary password provided by an admin, once reset you can login as normal using the new password
          security: []
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/PassResetTemp"
          responses:
            200:
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
      /user/role:
        get:
          summary: generates a list of all user roles
          parameters:
            - in: query
              name: offset
              type: integer
              description: The number of items to skip before starting to collect the result set
            - in: query
              name: limit
              type: integer
              description: The numbers of items to return
          responses:
            200:
              description:  full roles list
              schema:
                type: array
                items:
                  $ref: "#/definitions/UserRole"
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        post:
          summary: creates a new role
          parameters:
            - in: body
              name: body
              description: the id field here is not used so you can put any number to pass the validation
              schema:
                $ref: "#/definitions/UserRole"
          responses:
            200:
              description: the id of the created role.
              schema:
                type: object
                properties:
                  id :
                    type: integer
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        put:
          summary: updates a role
          parameters:
            - in: body
              name: body
              schema:
                $ref: "#/definitions/UserRole"
          responses:
            200:
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
        delete:
          summary: deletes a role
          parameters:
            - in: body
              name: body
              schema:
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
          responses:
            200:
              description: role deleted
            401:
              $ref: "#/responses/UnauthorizedError"
            default:
              $ref: "#/responses/DefaultError"
    responses:
      UnauthorizedError:
        description: Authentication is missing or invalid
        schema:
          $ref: "#/definitions/Response"
      UserExistsError:
        description: Username already taken
        schema:
          $ref: "#/definitions/Response"
      DefaultError:
        description: Generic Error used for most error responses - it returns a custom code and message depending on the reply context
        schema:
          $ref: "#/definitions/Response"
    definitions:
      Jwt:
          type: object
          required:
          - "jwt"
          properties:
            jwt:
              type: string
      F2aAuth:
          type: object
          required:
          - jwt
          - f2a
          properties:
            jwt:
              type: string
              description: the jwt token accuired form the initial login
            f2a:
              type: string
              description: the  2 factor time code accuired from the google authenticator app
      PassReset:
          type: object
          required:
          - "id_profile"
          - "password_new"
          properties:
            id_profile:
              type: integer
            password_old:
              type: string
            password_new:
              type: string
      PassResetTemp:
          type: object
          required:
          - jwt
          - passwordNew
          properties:
            jwt:
              type: string
              description: the jwt token accuired form the initial login
            passwordNew:
              type: string
              description: the new password for this user
      F2aDisable:
          type: object
          required:
          - password
          properties:
            password:
              type: string
      F2aEnable:
          type: object
          required:
            - code
            - secret
          properties:
            code:
              type: string
              description: the 2 factor code generted by the android app after scanning the barcode
            secret:
              type: string
              description: the master password which will be used to for decoding
      Login:
          type: object
          required:
            - username
            - password
          properties:
            username:
              type: string
            password:
              type: string
          example:
                username: "[email protected]"
                password: "password"
      Profile:
          type: object
          required:
          - username
          - password
          - active
          - role
          - tenant_id
          - person_id
          - reset_password_next_login
          properties:
            username:
              type: string
            password:
              type: string
            reset_password_next_login:
              type: boolean
            active:
              type: boolean
            email:
              type: string
            role:
                items:
                    type: integer
            tenant_id:
              type: integer
            person_id:
              type: integer
          example:
                username: "username"
                email: "[email protected]"
                password: "password"
                active: true
                reset_password_next_login: false
                tenant_id: 1
                person_id: 1
                role:
                  - 1
                  - 2
      ProfileUpdate:
        type: object
        required:
          - id
        properties:
          id:
            type: integer
          username:
            type: string
          reset_password_next_login:
            type: string
            enum:
              - "true"
              - "false"
    
          password:
            type: string
          active:
            type: string
            enum:
              - "true"
              - "false"
          email:
            type: string
          role:
              items:
                  type: integer
          tenant_id:
            type: integer
          person_id:
            type: integer
        example:
              id: 1
              username: "username"
              email: "[email protected]"
              password: "password"
              reset_password_next_login: "false"
              active: "true"
              tenant_id: 1
              person_id: 1
              role:
                - 1
                - 2
      UserRole:
          type: object
          required:
            - name
            - id
            - data
          properties:
            id:
              type: integer
            name:
              type: string
            data:
              type: string
      Response:
        type: object
        properties:
          code:
            type: integer
          message:
            type: string
        required:
          - code
          - message
        example:
              code: "500"
              message: "Server error"
    securityDefinitions:
       jwt:
        type: apiKey
        in: header
        name: x-jwt
    
    opened by krasi-georgiev 17
Releases(v0.30.3)
Go implementation of the Rust `dbg` macro

godbg ?? godbg is an implementation of the Rust2018 builtin debugging macro dbg. The purpose of this package is to provide a better and more effective

Tyler Wince 187 Oct 22, 2022
Functional programming library for Go including a lazy list implementation and some of the most usual functions.

functional A functional programming library including a lazy list implementation and some of the most usual functions. import FP "github.com/tcard/fun

Toni Cárdenas 31 May 21, 2022
Go implementation of the XDG Base Directory Specification and XDG user directories

xdg Provides an implementation of the XDG Base Directory Specification. The specification defines a set of standard paths for storing application file

Adrian-George Bostan 294 Nov 18, 2022
Simple Client Implementation of WebFinger

Go-Webfinger Go client for the Webfinger protocol Go-Webfinger is a Go client for the Webfinger protocol. *It is a work in progress, the API is not fr

Antoine Imbert 17 Nov 18, 2022
An example client implementation written in GO to access the CyberVox platform API

About This is an example client implementation written in GO to access the CyberVox platform API.

Cyberlabs AI 15 Nov 7, 2022
An implementation of standard generics APIs in Go.

generics This package shows an implementation outlook of proposed generics APIs import "changkun.de/x/generics" Related issues: golang/go#45458 golang

Changkun Ou 26 Mar 3, 2022
a quick golang implementation of google pubsub subscriber for testing with the emulator.

gosub a quick golang implementation of google pubsub subscriber for testing with the emulator. it does one thing which is subscribing to a topic and r

Nam Pham 1 Oct 23, 2021
Go implementation Welford’s method for one-pass variance computation

Variance and standard deviation caluculation using variance's algorithm Table of Contents Introduction Installation Usage Contributing License Introdu

Axiom, Inc. 7 Jun 5, 2022
Go implementation of Donald Knuth's Algorithm 7.2.2.1C for exact cover with colors.

go-dlx Go implementation of Donald Knuth's Algorithm 7.2.2.1C for exact cover with colors. This code is based on the Algorithm C described in http://w

Soojin Nam 5 Nov 25, 2022
A simple and sussy project is an implementation of SOMMIP Lab 1 written in Golang

SOMMIP Lab 1 Isac Arthur Table of Contents About The Project Getting Started Prerequisites Installation Supported commands About The Project This very

Arthur 1 Nov 10, 2021
Implementation of the test task, chat in the goland language

Implementation of the test task, chat in the goland language

Dmitriy Fofanov 1 Dec 5, 2021
Rule engine implementation in Golang

Rule engine implementation in Golang

Hyperjump 1.5k Nov 27, 2022
Refrence implementation of the globaldce protocol

globaldce-toolbox This is the reference implementation of globaldce protocole coded in the go programming language. This project is still experimental

globaldce 29 Nov 16, 2022
The official golang implementation for Project Anatha.

Project Anatha The official golang implementation for Project Anatha. For instructions on setting up a validator on the Anatha network, view the guide

潘毅 0 Nov 25, 2021
The official Go implementation for interacting with the TonicPow API

The official Go implementation for interacting with the TonicPow API Table of Contents Installation Documentation Examples & Tests Benchmarks Code Sta

TonicPow 8 Jan 17, 2022
A Go implementation of Rust's evmap

A Go implementation of Rust's evmap which optimizes for high-read, low-write workloads and uses eventual consistency to ensure that readers and writers never block each other.

Clark McCauley 9 Sep 3, 2022
An ease to use finit state machine golang implementation.Turn any struct to a fsm with graphviz visualization supported.

go-fsm An ease to use finit state machine golang implementation.Turn any struct to a fsm with graphviz visualization supported. usage import github.co

FingerLiu 5 Dec 26, 2021
gopbin is a minimalist and opinionated pastebin implementation written in Go.

gopbin gopbin is a minimalist and opinionated pastebin implementation written in

D. Henkes 0 Dec 28, 2021
Flesch-go - Go-based implementation of the Flesch reading ease readability formula module.

flesch-go Go-based implementation of the Flesch reading ease readability formula module. Thanks for the flesch-index project. Installation Run the fol

Afeyer 2 Nov 9, 2022