swaggo / swag Goto Github PK

View Code? Open in Web Editor NEW

9.8K 86.0 1.1K 5.06 MB

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

License: MIT License

Go 99.56% Makefile 0.29% Dockerfile 0.14%

golang swagger swagger2 annotations openapi

swag's People

Contributors

Stargazers

Watchers

Forkers

eashevchenko pilere gen0cide dimshadowww forging2012 selmanj ryfloyd bestplay bas24 rookiejin richardyicai rinetd jayhuang75 duanlizhi xykong easonlin404 manveru zhwei820 nadilas gitter-badger kentana jfkriz jsrj78 2892931976 cia-rana do-somethings acontrer slax0rr ispec-inc murawakimitsuhiro liwei0903nn troyanov amirsoleimani tanan glebtv paragtokopedia harrypod hykuan syossan27 renesugar profsmallpine renyucheng wksw skatsuta bongsakorn gimox war1oc jasonhancock h4v0kh3l1 ricmalta cparratto abdulito dselans fullstop000 collinmsn vafinvr mulansoft alanzoni onesafe anarcher aerbin wheniwork imjerrybao ashtonian elvizlai francisco-berridi schigh jameselsey armandocolpa brucify l3xx shammishailaj rubensayshi kaythxbye zvictorino kinganeng idagio temorfeouz kyawmyintthein nerzal hexl21 edevil sebdott borizes agarwal-nitesh zarmin schinery jdomzhang kazu22002 yangmiok z2665 zapkub alauda flyyingzi whiteand kolaente morihara-y trendingtechnology ryanadex sanleon

swag's Issues

Add Array and Multi-Value Parameters

https://swagger.io/docs/specification/2-0/describing-parameters/

      # color=red,black,white
      parameters:
        - in: query
          name: color
          type: array
          collectionFormat: csv
          items:
            type: string

// @Param some_id []query true "Some ID" uniqueItems(true) minnux(0)

Serving swag document without any other GoWebFramework

Hi, could you update the README to show an example of how to using swagger.json(yaml) directly in a Go Web App alone, not with any GoWebFramework?

Support empty responses

According to the swagger 2.0 docs, you can describe a response with an empty body by not providing a schema:

Some responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify a schema for the response. Swagger treats no schema as a response without a body.

However, using the @success tag requires that schema be specified (at least according to the regex here: https://github.com/swaggo/swag/blob/master/operation.go#L190)

Ideally, one could specify a response has no body by being able to write @success 200 "My description goes here"

Swag parses comments rule.

it`s will be very slowly that the vendor directory are included in the Parser.files map

//   in windows  "/vendor"  would be "\vendor" so i think it just make vendor will be ok ! 
if ext := filepath.Ext(path) ; ext == ".go" && !strings.Contains(path , "/vendor"){
			astFile , err := parser.ParseFile(token.NewFileSet() ,path ,nil, parser.ParseComments)
			if err != nil {
				panic(err)
			}
			log.Println(path)
			p.files [path] = astFile
		}
		return nil

Add lint for swagger.

Support anonymous field parsing

ref swaggo/gin-swagger#7

Can not find the "github.com/swaggo/gin-swagger"

Hello,

First of all, great package. But I follow the use guide, and seems i can not find the

"github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles"

Please advices.

feat: added reftype in swagger.definitions

Checking refType has existing in 'TypeDefinitions'

TypeDefinitions is map [package name][type name][ast.TypeSpec], we should check if instead of real package name.

Add support XML

Complex types support

type MyXML struct {
XMLName       *xml.Name `xml:"data" json:",omitempty"`
}

yields

panic: not supported 'astSelectorExpr' yet.

Any ideas how this can be fixed?

Add Default Parameter Values

https://swagger.io/docs/specification/2-0/describing-parameters/

Add a "tags" swagger

Can you add a tags to parse swag?

"get": {
"tags": ["operations"],
"description": "",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],

Flattened code struct

Add example in request body json

For example.

type Bottle struct {
	ID        int    `json:"id"`
	Name      string `json:"name"`
	AccountID int    `json:"account_id"`
}

// GetExample get method example
// @Summary Add a new pet to the store
// @Description get string by ID
// @ID id
// @Accept json
// @Produce json
// @Param bottles body model.Bottle true "bottle info"
// @Success 200 {object} model.Bottle "bottle info" <--- 
// @Router /bottles [post]
func PostBottles(c echo.Context) error {
	b := model.Bottle{
		ID:        1,
		Name:      "Bottle",
		AccountID: 1,
	}
	return c.JSON(http.StatusOK, b)
}

Display json example in swagger.

{
  "account_id": 0,
  "id": 0,
  "name": "string"
}

I want to real example.
https://swagger.io/docs/specification/2-0/adding-examples/

{
  "account_id": 1,
  "id": 2,
  "name": "red wine No14"
}

What kind of plan are you planning to do in the future?

By the way, I thought approach.

type Bottle struct {
	ID        int    `json:"id" example:"2"`
	Name      string `json:"name" example:"red wine No14"`
	AccountID int    `json:"account_id" example:"1"`
}

Support @Produce application/x-json-stream

Does the code have to validate MIME types? This one (line-separated JSON) is popular in streaming REST APIs.

Add data type for json

type Tag struct {
	ID    int64       `json:"id"`
	Name  string    `json:"name"`
	Data  time.Time `json:"data"`
}

 type: "object"
  properties:
    id:
     type: "integer"
     format: "int64"

Doc: https://swagger.io/specification/#dataTypeFormat

Unknown Type: int

Hello All,

I try to implement the example as follow.
My type is:
type SwaggerProjectList struct { ProjectId string ProjectName string NumTasks int }

My Swaggo comments
// @Success 200 {object} models.SwaggerProjectList "project list"

The problem is in swaggo UI:
{ "NumTasks": "Unknown Type: int", "ProjectId": "string", "ProjectName": "string" }

Please support tags description

tags:
  - name: pets
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders

Add suport for array of structs

See #39 (comment)

Pr

#20

enable files upload

Improve code coverage

codebeat: too many return values

at swag.Parser.parseField return 5 values
https://codebeat.co/projects/github-com-swaggo-swag-master/pull_requests/119111#9648392

Please support satori/uuid

has error do swag init when use uuid.UUID

account.go

package account

import uuid "github.com/satori/go.uuid"

// Account account struct
type Account struct {
	ID       uuid.UUID `json:"id"`
	Email    string    `json:"email"`
	Password string    `json:"password"`
}

account_controller.go

package controller

import (
	"net/http"

	"github.com/go-examples/swaggo-sample/account"
	"github.com/labstack/echo"
	uuid "github.com/satori/go.uuid"
)

// AccountController account controller
type AccountController struct{}

// NewAccountController mount account controller
func NewAccountController(e *echo.Echo) {
	handler := &AccountController{}

	e.GET("/accounts/:id", handler.Show)
}

// Show show account
// @Summary Show a account
// @Description get account by ID
// @Accept json
// @Produce json
// @Param id path uuid.UUID true "Account ID"
// @Success 200 {object} account.Account
// @Router /accounts/{id} [get]
func (c *AccountController) Show(ctx echo.Context) error {
	res := &account.Account{
		ID:       uuid.NewV4(),
		Email:    "[email protected]",
		Password: "asdf0987",
	}

	return ctx.JSON(http.StatusOK, res)
}

error message

$ swag init
2018/04/13 10:04:20 Generate swagger docs....
2018/04/13 10:04:20 Generate general API Info
panic: not supported 'astSelectorExpr' yet.

goroutine 1 [running]:
github.com/swaggo/swag.getPropertyName(0xc420330580, 0x30, 0x13fc780, 0xe401, 0xc420408150)
	/Users/ogura/go/src/github.com/swaggo/swag/property.go:23 +0x820
github.com/swaggo/swag.(*Parser).parseField(0xc420136620, 0xc420330580, 0xc420408150, 0x0, 0xc420408150, 0xc420107910, 0x20101454d, 0x10, 0x0, 0xc41fff7a3c)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:467 +0x40
github.com/swaggo/swag.(*Parser).parseStruct(0xc420136620, 0xc420486349, 0x7, 0xc420330580, 0x15201089a8)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:399 +0x9e
github.com/swaggo/swag.(*Parser).parseTypeSpec(0xc420136620, 0xc420486349, 0x7, 0xc4201244e0, 0xc420408120)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:381 +0x25a
github.com/swaggo/swag.(*Parser).ParseDefinition(0xc420136620, 0xc420486349, 0x7, 0xc4201244e0, 0xc420428288, 0x7)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:351 +0x11b
github.com/swaggo/swag.(*Parser).ParseDefinitions(0xc420136620)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:334 +0xbd
github.com/swaggo/swag.(*Parser).ParseAPI(0xc420136620, 0x141907e, 0x2, 0x141a014, 0x7)
	/Users/ogura/go/src/github.com/swaggo/swag/parser.go:74 +0x268
github.com/swaggo/swag/gen.(*Gen).Build(0xc420109a08, 0x141907e, 0x2, 0x141a014, 0x7, 0x141bde3, 0xe, 0x0, 0x0, 0x0, ...)
	/Users/ogura/go/src/github.com/swaggo/swag/gen/gen.go:28 +0x399
main.main.func1(0xc42008a160, 0xc420128100, 0xc42008a160)
	/Users/ogura/go/src/github.com/swaggo/swag/cmd/swag/main.go:23 +0x108
github.com/urfave/cli.HandleAction(0x1398260, 0x14312b0, 0xc42008a160, 0x0, 0xc420128240)
	/Users/ogura/go/src/github.com/urfave/cli/app.go:501 +0xd2
github.com/urfave/cli.Command.Run(0x14195f7, 0x4, 0x0, 0x0, 0xc420126010, 0x1, 0x1, 0x141be6f, 0xe, 0x0, ...)
	/Users/ogura/go/src/github.com/urfave/cli/command.go:165 +0x4bb
github.com/urfave/cli.(*App).Run(0xc42013a000, 0xc42000c060, 0x2, 0x2, 0x0, 0x0)
	/Users/ogura/go/src/github.com/urfave/cli/app.go:259 +0x740
main.main()
	/Users/ogura/go/src/github.com/swaggo/swag/cmd/swag/main.go:45 +0x42a

Support for time.Time as a structure field

Ref

feat: add router parameters in swagger object

Cant type in Multitple Query Parameter

If i Define multiple Query Parameter in Swagger JSON file then i am not able to type in any of them . But if i keep it to one query parameter then i can type .. any fix for that ?

Please support operationId

With this, there will generate html anchor in page.

swag init then automatically adding the example in the doc

I found something so weird. before is working fine. but seems now I run swag init. it will automatically add the example /testapi/get-struct-array-by-string/{some_id} on the doc.

Please advices

Add output swagger json and yaml

Add Cli option

for example

swag --swagger ./swagger --dir ./ --generalInfo main.go

swagger
Output the swagger conf for json and yaml
dir
Directory you want to parse
generalInfo
Go file path in which 'swagger general API Info' is written

this line panic on parsing

swag/parser.go

Line 135 in abf4f7b

log.Panicf("ParseComment panic:%+v", err)

panic: ParseComment panic:Can not find ref type: ...
with a type from another package of the form MyStructs.TheStructToUse

I don't get why ....
Stéphane

How to add the custom request header

Hello,

I'm wondering how I can add the custom request header? for example JWT.

Add net/http WrapHandler

Thank you for a nice OSS.
I want to use net/http.
There are probably many people who think so.

I created WrapHandler for net/http
https://github.com/pei0804/go-http-swagger

Is it possible to include this in the repository?
For examle custome error. more test cases...
If there is a problem I am motivated to improve.

tests: use testdata instand of example folder

Add support for security

https://swagger.io/docs/specification/2-0/authentication/

Docs generation loop

I'm getting too many messages when generating docs by swag init:

➜  api git:(master) swag init
2018/04/08 19:00:18 Generate swagger docs....
2018/04/08 19:00:18 Generate general API Info
2018/04/08 19:00:18 Generating models.Transaction
2018/04/08 19:00:18 Generating models.Wallet
2018/04/08 19:00:18 Skipping 'models.Wallet', already present.
2018/04/08 19:00:18 Skipping 'models.Wallet', already present.
2018/04/08 19:00:18 Skipping 'models.Wallet', already present.
2018/04/08 19:00:18 Skipping 'models.Wallet', already present.
2018/04/08 19:00:18 Skipping 'models.Wallet', already present.
...

2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
2018/04/08 23:45:34 Skipping 'models.Wallet', already present.
runtime: goroutine stack exceeds 1000000000-byte limit
fatal error: stack overflow

runtime stack:
runtime.throw(0x140f46e, 0xe)
	/usr/local/Cellar/go/1.10.1/libexec/src/runtime/panic.go:616 +0x81
runtime.newstack()
	/usr/local/Cellar/go/1.10.1/libexec/src/runtime/stack.go:1054 +0x71f
runtime.morestack()
	/usr/local/Cellar/go/1.10.1/libexec/src/runtime/asm_amd64.s:480 +0x89

goroutine 1 [running]:
github.com/swaggo/swag.(*Parser).parseStruct(0xc4204057a0, 0xc4203d4499, 0x6, 0xc4201febc0, 0x0)
	/Users/drubtsov/.go/src/github.com/swaggo/swag/parser.go:397 +0xf33 fp=0xc440600a08 sp=0xc440600a00 pc=0x131f413
github.com/swaggo/swag.(*Parser).parseTypeSpec(0xc4204057a0, 0xc4203d4499, 0x6, 0xc420420e40, 0xc43a048f00)
	/Users/drubtsov/.go/src/github.com/swaggo/swag/parser.go:381 +0x24d fp=0xc440600f18 sp=0xc440600a08 pc=0x131e37d
github.com/swaggo/swag.(*Parser).ParseDefinition(0xc4204057a0, 0xc4203d4499, 0x6, 0xc420420e40, 0xc43a044486, 0x6)
	/Users/drubtsov/.go/src/github.com/swaggo/swag/parser.go:351 +0xf9 fp=0xc440601688 sp=0xc440600f18 pc=0x131dbd9
github.com/swaggo/swag.(*Parser).parseStruct(0xc4204057a0, 0xc4203d4499, 0x6, 0xc4201fee40, 0xc43a048e70)

...additional frames elided...

One doc declaration:

// @Summary Update current user
// @ID update-user
// @Accept  json
// @Produce  json
// @Success 200 {object} models.User
// @Router /v1/user [put]
func (*userControllers) Update(c *gin.Context) {}

My models:

type User struct {
	ID            uint     `json:"id" gorm:"primary_key;unique"`
	Email         string   `json:"email" gorm:"unique_index"`
	PassHash      string   `json:"pass_hash"`
	Role          string   `json:"role"`
	Wallets       []Wallet `gorm:"foreignkey:OwnerID;association_foreignkey:ID"`
	FamiliesOwner []Family `json:"families" gorm:"foreignkey:OwnerID;association_foreignkey:ID"`
	Families      []Family `gorm:"many2many:user_families;"`
}

type Wallet struct {
	ID           uint          `json:"id" gorm:"primary_key;unique"`
	OwnerID      uint          `json:"owner_id"`
	FamilyID     uint          `json:"family_id"`
	CurrencyID   uint          `json:"currency_id"`
	Value        float64       `json:"value"`
	IsDeleted    bool          `json:"is_deleted"`
	Transactions []Transaction `json:"transactions" gorm:"foreignkey:WalletID;association_foreignkey:ID"`
}

type Transaction struct {
	ID       uint      `json:"id" gorm:"primary_key;unique"`
	WalletID uint      `json:"wallet_id"`
	Value    uint      `json:"value"`
	Date     time.Time `json:"date"`
}

Also, Maybe I can skip some fields in struct for a documentation?

Does repo include lint in future?

Are you planning to add lint in the future?
Because it contains code that will cause some lint errors at this time.

Want to use json key

Source request format

type Bottle struct {
	ID        int    `json:"id"`
	Name      string `json:"name"`
	AccountID int    `json:"account_id"`
}

Gen request format

{
  "AccountID": 0,
  "ID": 0,
  "Name": "string"
}

// GetExample get method example
// @Summary Add a new pet to the store
// @Description get string by ID
// @ID id
// @Accept json
// @Produce json
// @Param bottles body model.Bottle true "bottle info"
// @Success 200 {object} model.Bottle "bottle info"
// @Router /bottles [post]
func PostBottles(c echo.Context) error {
	b := model.Bottle{
		ID:        1,
		Name:      "Bottle",
		AccountID: 1,
	}
	return c.JSON(http.StatusOK, b)
}

Want to request format

{
  "account_id": 0,
  "id": 0,
  "name": "string"
}

I update this.
pei0804@051cd3e

Is it possible to include this in master?

Add example value supported for object, array

#55
#56

travis ci go1.8.x build failed

https://travis-ci.org/swaggo/swag/jobs/352730132

I cloud not install swag as the guide from readme

Hi team,
Thanks so much for your work.

Update: I fixed it! You must to set GOPATH env in case you have custom GOROOT env.

I have an installation issue: the installation is done without error, but the command is not found.
I'm using Ubuntu 14

go get -v -u github.com/swaggo/swag/cmd/swag

github.com/swaggo/swag (download)
github.com/ghodss/yaml (download)
Fetching https://gopkg.in/yaml.v2?go-get=1
Parsing meta tags from https://gopkg.in/yaml.v2?go-get=1 (status code 200)
get "gopkg.in/yaml.v2": found meta tag get.metaImport{Prefix:"gopkg.in/yaml.v2", VCS:"git", RepoRoot:"https://gopkg.in/yaml.v2"} at https://gopkg.in/yaml.v2?go-get=1
gopkg.in/yaml.v2 (download)
github.com/go-openapi/jsonreference (download)
github.com/PuerkitoBio/purell (download)
github.com/PuerkitoBio/urlesc (download)
Fetching https://golang.org/x/net/idna?go-get=1
Parsing meta tags from https://golang.org/x/net/idna?go-get=1 (status code 200)
get "golang.org/x/net/idna": found meta tag get.metaImport{Prefix:"golang.org/x/net", VCS:"git", RepoRoot:"https://go.googlesource.com/net"} at https://golang.org/x/net/idna?go-get=1
get "golang.org/x/net/idna": verifying non-authoritative meta tag
Fetching https://golang.org/x/net?go-get=1
Parsing meta tags from https://golang.org/x/net?go-get=1 (status code 200)
golang.org/x/net (download)
Fetching https://golang.org/x/text/secure/bidirule?go-get=1
Parsing meta tags from https://golang.org/x/text/secure/bidirule?go-get=1 (status code 200)
get "golang.org/x/text/secure/bidirule": found meta tag get.metaImport{Prefix:"golang.org/x/text", VCS:"git", RepoRoot:"https://go.googlesource.com/text"} at https://golang.org/x/text/secure/bidirule?go-get=1
get "golang.org/x/text/secure/bidirule": verifying non-authoritative meta tag
Fetching https://golang.org/x/text?go-get=1
Parsing meta tags from https://golang.org/x/text?go-get=1 (status code 200)
golang.org/x/text (download)
Fetching https://golang.org/x/text/transform?go-get=1
Parsing meta tags from https://golang.org/x/text/transform?go-get=1 (status code 200)
get "golang.org/x/text/transform": found meta tag get.metaImport{Prefix:"golang.org/x/text", VCS:"git", RepoRoot:"https://go.googlesource.com/text"} at https://golang.org/x/text/transform?go-get=1
get "golang.org/x/text/transform": verifying non-authoritative meta tag
Fetching https://golang.org/x/text/unicode/bidi?go-get=1
Parsing meta tags from https://golang.org/x/text/unicode/bidi?go-get=1 (status code 200)
get "golang.org/x/text/unicode/bidi": found meta tag get.metaImport{Prefix:"golang.org/x/text", VCS:"git", RepoRoot:"https://go.googlesource.com/text"} at https://golang.org/x/text/unicode/bidi?go-get=1
get "golang.org/x/text/unicode/bidi": verifying non-authoritative meta tag
Fetching https://golang.org/x/text/unicode/norm?go-get=1
Parsing meta tags from https://golang.org/x/text/unicode/norm?go-get=1 (status code 200)
get "golang.org/x/text/unicode/norm": found meta tag get.metaImport{Prefix:"golang.org/x/text", VCS:"git", RepoRoot:"https://go.googlesource.com/text"} at https://golang.org/x/text/unicode/norm?go-get=1
get "golang.org/x/text/unicode/norm": verifying non-authoritative meta tag
Fetching https://golang.org/x/text/width?go-get=1
Parsing meta tags from https://golang.org/x/text/width?go-get=1 (status code 200)
get "golang.org/x/text/width": found meta tag get.metaImport{Prefix:"golang.org/x/text", VCS:"git", RepoRoot:"https://go.googlesource.com/text"} at https://golang.org/x/text/width?go-get=1
get "golang.org/x/text/width": verifying non-authoritative meta tag
github.com/go-openapi/jsonpointer (download)
github.com/go-openapi/swag (download)
github.com/mailru/easyjson (download)
github.com/go-openapi/spec (download)
github.com/urfave/cli (download)

swag init

No command 'swag' found, did you mean:
 Command 'swig' from package 'swig' (main)
 Command 'swab' from package 'odin' (universe)
swag: command not found

Schema error at paths['/accounts'].get.responses['400']
should have required property 'description'
missingProperty: description

swag/example/celler/docs/swagger/swagger.json

Line 39 in a0011c3

"responses": {

using gin
no port declared so gin is using the default port

Add Validation(max, min)

https://swagger.io/docs/specification/2-0/describing-parameters/

        - in: query
          name: limit
          type: integer
          required: false
          default: 20
          minimum: 1 <--
          maximum: 100 <--
          description: The numbers of items to return.

[get] and [post] with the same path, only one is generated

If I have two functions with different methods, only the second one appears in the swagger:

e.g.

// @Router /v1/somepath [get]
func (controller *SomeController) DoSomething() gin.HandlerFunc {

// @Router /v1/somepath [post]
func (controller *SomeController) DoSomethingElse() gin.HandlerFunc {

swaggo / swag Goto Github PK

swag's People

Contributors

Stargazers

Watchers

Forkers

swag's Issues

Recommend Projects

Recommend Topics

Recommend Org