swaggo / swag Goto Github PK
View Code? Open in Web Editor NEWAutomatically generate RESTful API documentation with Swagger 2.0 for Go.
License: MIT License
Automatically generate RESTful API documentation with Swagger 2.0 for Go.
License: MIT License
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)
Nice job thus far, but you did not include any how to for the standard library users.
Hello,
I'm wondering how I can add the custom request header? for example JWT.
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
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 {
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" }
tags:
- name: pets
description: Everything about your Pets
- name: store
description: Access to Petstore orders
at swag.Parser.parseField return 5 values
https://codebeat.co/projects/github-com-swaggo-swag-master/pull_requests/119111#9648392
See #39 (comment)
I should add description in responses.
Schema error at paths['/accounts'].get.responses['400']
should have required property 'description'
missingProperty: description
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?
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.
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?
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.
don't know if is a gin or a swag problem so i posted it in both repos
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.
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"`
}
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
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?
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 ?
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.
TypeDefinitions
is map [package name][type name][ast.TypeSpec]
, we should check if instead of real package name.
Can you add a tags to parse swag?
"get": {
"tags": ["operations"],
"description": "",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
Are you planning to add lint in the future?
Because it contains code that will cause some lint errors at this time.
type Tag struct {
ID int64 `json:"id"`
Name string `json:"name"`
Data time.Time `json:"data"`
}
type: "object"
properties:
id:
type: "integer"
format: "int64"
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?
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
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
enable files upload
Line 135 in abf4f7b
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
Does the code have to validate MIME types? This one (line-separated JSON) is popular in streaming REST APIs.
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
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"
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.