swaggo / swag Goto Github PK

View Code? Open in Web Editor NEW

10.3K 88.0 1.2K 5.05 MB

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

License: MIT License

Go 99.54% Makefile 0.29% Dockerfile 0.17%

golang swagger swagger2 annotations openapi

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)

Implementation for standard Library.

Nice job thus far, but you did not include any how to for the standard library users.

How to add the custom request header

Hello,

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

tests: use testdata instand of example folder

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

[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 {

Add example value supported for object, array

#55
#56

Add lint for swagger.

Improve code coverage

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

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

Add suport for array of structs

See #39 (comment)

schema error in response

I should add description in responses.

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": {

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?

Support for deep models

Is there a way to get deep models working? Right now if I have a struct inside another struct, it doesn't recognize the top struct. Similarly bool (type bool) isn't recognized either.

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?

Add enums func

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

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.

Support for time.Time as a structure field

Ref

Support parsing interface type in swagger schema object

feat: add router parameters in swagger object

swag-cli doesn't configure port

don't know if is a gin or a swag problem so i posted it in both repos

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.

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"`
}

Please support operationId

With this, there will generate html anchor in page.

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

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 Default Parameter Values

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

Support anonymous field parsing

ref swaggo/gin-swagger#7

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 ?

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.

Checking refType has existing in 'TypeDefinitions'

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

build failed at 1.10.x version

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

Add a "tags" swagger

Can you add a tags to parse swag?

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

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.

Add support for security

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

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

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?

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

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

Pr

#20

enable files upload

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

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.

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

feat: added reftype in swagger.definitions

travis ci go1.8.x build failed

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

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"

can not support Type in denpency and interface Type

for example , a struct like below :
type VO struct{
code: string
msg : string
data: interface {}
}
I can not reference it in response annotation

also ,can not reference a type not in current file :
VoMap defined in other package
c.JSON(http.StatusOK, VoMap{"code": 200, "org": org})

swaggo / swag Goto Github PK

swag's Issues

Recommend Projects

Recommend Topics

Recommend Org