swag

package module
v1.7.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 17, 2025 License: MIT Imports: 28 Imported by: 0

README

swag

🌍 English ∙ 简体中文

Travis Status Coverage Status Go Report Card codebeat badge Go Doc Backers on Open Collective Sponsors on Open Collective FOSSA Status Release

Swag将Go的注释转换为Swagger2.0文档。我们为流行的 Go Web Framework 创建了各种插件，这样可以与现有Go项目快速集成（使用Swagger UI）。

目录

快速开始

  1. 将注释添加到API源代码中，请参阅声明性注释格式。
  2. 使用如下命令下载swag：
$ go get -u github.com/maxliu9403/action-swag/cmd/action-swag

# 1.16 及以上版本
$ go install github.com/maxliu9403/action-swag/cmd/action-swag@latest

从源码开始构建的话，需要有Go环境（1.13及以上版本）。

  1. 在包含main.go文件的项目根目录运行action-swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）。
action-swag init

确保导入了生成的docs/docs.go文件，这样特定的配置文件才会被初始化。如果通用API指数没有写在main.go中，可以使用-g标识符来告知swag。

action-swag init -g http/api.go
  1. (可选) 使用action-swag fmt格式化 SWAG 注释。(请先升级到最新版本)
action-swag fmt

swag cli

action-swag init -h
NAME:
   action-swag init - Create docs.go

USAGE:
   action-swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

action-swag fmt -h
NAME:
   action-swag fmt - format swag comments

USAGE:
   action-swag fmt [command options] [arguments...]

OPTIONS:
   --dir value, -d value          API解析目录 (默认: "./")
   --exclude value                解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --generalInfo value, -g value  API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --help, -h                     show help (default: false)

支持的Web框架

如何与Gin集成

点击此处查看示例源代码。

  1. 使用action-swag init生成Swagger2.0文档后，导入如下代码包：
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
  1. 在main.go源代码中添加通用的API注释：
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth
func main() {
    r := gin.Default()

    c := controller.NewController()

    v1 := r.Group("/api/v1")
    {
        accounts := v1.Group("/accounts")
        {
            accounts.GET(":id", c.ShowAccount)
            accounts.GET("", c.ListAccounts)
            accounts.POST("", c.AddAccount)
            accounts.DELETE(":id", c.DeleteAccount)
            accounts.PATCH(":id", c.UpdateAccount)
            accounts.POST(":id/images", c.UploadAccountImage)
        }
    //...
    }
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}
//...

此外，可以动态设置一些通用的API信息。生成的代码包docs导出SwaggerInfo变量，使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例：

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"

    "./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

    // programatically set swagger info
    docs.SwaggerInfo.Title = "Swagger Example API"
    docs.SwaggerInfo.Description = "This is a sample server Petstore server."
    docs.SwaggerInfo.Version = "1.0"
    docs.SwaggerInfo.Host = "petstore.swagger.io"
    docs.SwaggerInfo.BasePath = "/v2"
    docs.SwaggerInfo.Schemes = []string{"http", "https"}

    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}
  1. 在controller代码中添加API操作注释：
package controller

import (
    "fmt"
    "net/http"
    "strconv"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/swag/example/celler/httputil"
    "github.com/swaggo/swag/example/celler/model"
)

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
func (c *Controller) ShowAccount(ctx *gin.Context) {
  id := ctx.Param("id")
  aid, err := strconv.Atoi(id)
  if err != nil {
    httputil.NewError(ctx, http.StatusBadRequest, err)
    return
  }
  account, err := model.AccountOne(aid)
  if err != nil {
    httputil.NewError(ctx, http.StatusNotFound, err)
    return
  }
  ctx.JSON(http.StatusOK, account)
}

// ListAccounts godoc
// @Summary      List accounts
// @Description  get accounts
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        q    query     string  false  "name search by q"  Format(email)
// @Success      200  {array}   model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {
  q := ctx.Request.URL.Query().Get("q")
  accounts, err := model.AccountsAll(q)
  if err != nil {
    httputil.NewError(ctx, http.StatusNotFound, err)
    return
  }
  ctx.JSON(http.StatusOK, accounts)
}
//...

action-swag init
  1. 运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档，如下所示：

swagger_index.html

格式化说明

可以针对Swag的注释自动格式化，就像go fmt。
此处查看格式化结果 here.

示例：

action-swag fmt

排除目录（不扫描）示例：

action-swag fmt -d ./ --exclude ./internal

开发现状

Swagger 2.0 文档

  • Basic Structure
  • API Host and Base Path
  • Paths and Operations
  • Describing Parameters
  • Describing Request Body
  • Describing Responses
  • MIME Types
  • Authentication
    • Basic Authentication
    • API Keys
  • Adding Examples
  • File Upload
  • Enums
  • Grouping Operations With Tags
  • Swagger Extensions

声明式注释格式

通用API信息

示例 celler/main.go

注释 说明 示例
title 必填 应用程序的名称。 // @title Swagger Example API
version 必填 提供应用程序API的版本。 // @version 1.0
description 应用程序的简短描述。 // @description This is a sample server celler server.
tag.name 标签的名称。 // @tag.name This is the name of the tag
tag.description 标签的描述。 // @tag.description Cool Description
tag.docs.url 标签的外部文档的URL。 // @tag.docs.url https://example.com
tag.docs.description 标签的外部文档说明。 // @tag.docs.description Best example documentation
termsOfService API的服务条款。 // @termsOfService http://swagger.io/terms/
contact.name 公开的API的联系信息。 // @contact.name API Support
contact.url 联系信息的URL。 必须采用网址格式。 // @contact.url http://www.swagger.io/support
contact.email 联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。 // @contact.email support@swagger.io
license.name 必填 用于API的许可证名称。 // @license.name Apache 2.0
license.url 用于API的许可证的URL。 必须采用网址格式。 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host 运行API的主机（主机名或IP地址）。 // @host localhost:8080
BasePath 运行API的基本路径。 // @BasePath /api/v1
accept API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。 // @accept json
produce API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。 // @produce json
query.collection.format 请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。 // @query.collection.format multi
schemes 用空格分隔的请求的传输协议。 // @schemes http https
x-name 扩展的键必须以x-开头，并且只能使用json值 // @x-example-key {"key": "value"}
使用Markdown描述

如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。

注释 说明 示例
title 必填 应用程序的名称。 // @title Swagger Example API
version 必填 提供应用程序API的版本。 // @version 1.0
description.markdown 应用程序的简短描述。 从api.md文件中解析。 这是@description的替代用法。 // @description.markdown No value needed, this parses the description from api.md
tag.name 标签的名称。 // @tag.name This is the name of the tag
tag.description.markdown 标签说明，这是tag.description的替代用法。 该描述将从名为tagname.md的文件中读取。 // @tag.description.markdown

API操作

Example celler/controller

注释 描述
description 操作行为的详细说明。
description.markdown 应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。
id 用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags 每个API操作的标签列表，以逗号分隔。
summary 该操作的简短摘要。
accept API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
produce API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
param 用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
security 每个API操作的安全性。
success 以空格分隔的成功响应。return code,{param type},data type,comment
failure 以空格分隔的故障响应。return code,{param type},data type,comment
response 与success、failure作用相同
header 以空格分隔的头字段。 return code,{param type},data type,comment
router 以空格分隔的路径定义。 path,[httpMethod]
x-name 扩展字段必须以x-开头，并且只能使用json值。

Mime类型

swag 接受所有格式正确的MIME类型, 即使匹配 */*。除此之外，swag还接受某些MIME类型的别名，如下所示：

Alias MIME Type
json application/json
xml text/xml
plain text/plain
html text/html
mpfd multipart/form-data
x-www-form-urlencoded application/x-www-form-urlencoded
json-api application/vnd.api+json
json-stream application/x-json-stream
octet-stream application/octet-stream
png image/png
jpeg image/jpeg
gif image/gif

参数类型

  • query
  • path
  • header
  • body
  • formData

数据类型

  • string (string)
  • integer (int, uint, uint32, uint64)
  • number (float32)
  • boolean (bool)
  • user defined struct

安全性

注释 描述 参数 示例
securitydefinitions.basic Basic auth. // @securityDefinitions.basic BasicAuth
securitydefinitions.apikey API key auth. in, name // @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application OAuth2 application auth. tokenUrl, scope // @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit OAuth2 implicit auth. authorizationUrl, scope // @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password OAuth2 password auth. tokenUrl, scope // @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode OAuth2 access code auth. tokenUrl, authorizationUrl, scope // @securitydefinitions.oauth2.accessCode OAuth2AccessCode
参数注释 示例
in // @in header
name // @name Authorization
tokenUrl // @tokenUrl https://example.com/oauth/token
authorizationurl // @authorizationurl https://example.com/oauth/authorize
scope.hoge // @scope.write Grants write access

属性

// @Param   enumstring  query     string     false  "string enums"       Enums(A, B, C)
// @Param   enumint     query     int        false  "int enums"          Enums(1, 2, 3)
// @Param   enumnumber  query     number     false  "int enums"          Enums(1.1, 1.2, 1.3)
// @Param   string      query     string     false  "string valid"       minlength(5)  maxlength(10)
// @Param   int         query     int        false  "int valid"          minimum(1)    maximum(10)
// @Param   default     query     string     false  "string default"     default(A)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

也适用于结构体字段：

type Foo struct {
    Bar string `minLength:"4" maxLength:"16"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux []string `enums:"foo,bar,baz"`
}
当前可用的
字段名 类型 描述
default * 声明如果未提供任何参数，则服务器将使用的默认参数值，例如，如果请求中的客户端未提供该参数，则用于控制每页结果数的“计数”可能默认为100。 （注意：“default”对于必需的参数没有意义）。参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。 与JSON模式不同，此值务必符合此参数的定义类型。
maximum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
maxLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums [*] 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
format string 上面提到的类型的扩展格式。有关更多详细信息，请参见数据类型格式。
collectionFormat string 指定query数组参数的格式。 可能的值为：
  • csv - 逗号分隔值 foo,bar.
  • ssv - 空格分隔值 foo bar.
  • tsv - 制表符分隔值 foo\tbar.
  • pipes - 管道符分隔值 foo|bar.
  • multi - 对应于多个参数实例，而不是单个实例 foo=bar＆foo=baz 的多个值。这仅对“query”或“formData”中的参数有效。
默认值是 csv。
进一步的
字段名 类型 描述
multipleOf number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern string See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
uniqueItems boolean See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.

样例

多行的描述

可以在常规api描述或路由定义中添加跨越多行的描述，如下所示：

// @description This is the first line
// @description This is the second line
// @description And so forth.
用户自定义的具有数组类型的结构
// @Success 200 {array} model.Account <-- This is a user defined struct.

package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}
响应对象中的模型组合
// JSONResult的data字段类型将被proto.Order类型替换
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"

type JSONResult struct {
    Code    int          `json:"code" `
    Message string       `json:"message"`
    Data    interface{}  `json:"data"`
}

type Order struct { //in `proto` package
    ...
}
  • 还支持对象数组和原始类型作为嵌套响应
@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
@success 200 {object} jsonresult.JSONResult{data=string} "desc"
@success 200 {object} jsonresult.JSONResult{data=[]string} "desc"
  • 替换多个字段的类型。如果某字段不存在，将添加该字段。
@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
在响应中增加头字段
// @Success      200              {string}  string    "ok"
// @failure      400              {string}  string    "error"
// @response     default          {string}  string    "other error"
// @Header       200              {string}  Location  "/entity/1"
// @Header       200,400,default  {string}  Token     "token"
// @Header       all              {string}  Token2    "token2"
使用多路径参数
/// ...
// @Param  group_id    path  int  true  "Group ID"
// @Param  account_id  path  int  true  "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]
结构体的示例值
type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
    PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
}
结构体描述
type Account struct {
    // ID this is userid
    ID   int    `json:"id"`
    Name string `json:"name"` // This is Name
}
使用swaggertype标签更改字段类型

#201

type TimestampTime struct {
    time.Time
}

///实现encoding.JSON.Marshaler接口
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
    bin := make([]byte, 16)
    bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
    return bin, nil
}

///实现encoding.JSON.Unmarshaler接口
func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
    v, err := strconv.ParseInt(string(bin), 10, 64)
    if err != nil {
        return err
    }
    t.Time = time.Unix(v, 0)
    return nil
}
///

type Account struct {
    // 使用`swaggertype`标签将别名类型更改为内置类型integer
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // 使用`swaggertype`标签更改struct类型为内置类型integer
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

    // Array types can be overridden using "array,<prim_type>" format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

#379

type CerticateKeyPair struct {
    Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
    Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}

生成的swagger文档如下：

"api.MyBinding": {
  "type":"object",
  "properties":{
    "crt":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    },
    "key":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    }
  }
}
使用swaggerignore标签排除字段
type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}
将扩展信息添加到结构字段
type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // 扩展字段必须以"x-"开头
}

生成swagger文档，如下所示：

"Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def",
            "x-omitempty": false
        }
    }
}
对展示的模型重命名
type Resp struct {
    Code int
}//@name Response
如何使用安全性注释

通用API信息。

// @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

每个API操作。

// @Security ApiKeyAuth

使用AND条件。

// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

项目相关

This project was inspired by yvasiyarov/swagger but we simplified the usage and added support a variety of web frameworks. Gopher image source is tenntenn/gopher-stickers. It has licenses creative commons licensing.

贡献者

This project exists thanks to all the people who contribute. [Contribute].

支持者

Thank you to all our backers! 🙏 [Become a backer]

赞助商

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

License

FOSSA Status

Documentation

Overview

Package swag converts Go annotations to Swagger Documentation 2.0. See https://github.com/swaggo/swag for more information about swag.

Index

Constants

View Source 
const (
	// CamelCase indicates using CamelCase strategy for struct field.
	CamelCase = "camelcase"

	// PascalCase indicates using PascalCase strategy for struct field.
	PascalCase = "pascalcase"

	// SnakeCase indicates using SnakeCase strategy for struct field.
	SnakeCase = "snakecase"
)
View Source 
const (
	// ARRAY represent a array value.
	ARRAY = "array"
	// OBJECT represent a object value.
	OBJECT = "object"
	// PRIMITIVE represent a primitive value.
	PRIMITIVE = "primitive"
	// BOOLEAN represent a boolean value.
	BOOLEAN = "boolean"
	// INTEGER represent a integer value.
	INTEGER = "integer"
	// NUMBER represent a number value.
	NUMBER = "number"
	// STRING represent a string value.
	STRING = "string"
	// FUNC represent a function value.
	FUNC = "func"
	// ANY represent a any value.
	ANY = "any"
	// NIL represent a empty value.
	NIL = "nil"
)
View Source 
const Name = "swagger"

Name is a unique name be used to register swag instance.

View Source 
const Version = "v1.7.6"

Version of swag.

Variables

View Source 
var (
	// ErrRecursiveParseStruct recursively parsing struct.
	ErrRecursiveParseStruct = errors.New("recursively parsing struct")

	// ErrFuncTypeField field type is func.
	ErrFuncTypeField = errors.New("field type is func")

	// ErrFailedConvertPrimitiveType Failed to convert for swag to interpretable type.
	ErrFailedConvertPrimitiveType = errors.New("swag property: failed convert primitive type")
)

Functions

func BuildCustomSchema 

func BuildCustomSchema(types []string) (*spec.Schema, error)

BuildCustomSchema build custom schema specified by tag swaggertype.

func CheckSchemaType 

func CheckSchemaType(typeName string) error

CheckSchemaType checks if typeName is not a name of primitive type.

func IsGolangPrimitiveType 

func IsGolangPrimitiveType(typeName string) bool

IsGolangPrimitiveType determine whether the type name is a golang primitive type.

func IsNumericType 

func IsNumericType(typeName string) bool

IsNumericType determines whether the swagger type name is a numeric type.

func IsPrimitiveType 

func IsPrimitiveType(typeName string) bool

IsPrimitiveType determine whether the type name is a primitive type.

func IsSimplePrimitiveType 

func IsSimplePrimitiveType(typeName string) bool

IsSimplePrimitiveType determine whether the type name is a simple primitive type.

func PrimitiveSchema 

func PrimitiveSchema(refType string) *spec.Schema

PrimitiveSchema build a primitive schema.

func ReadDoc 

func ReadDoc(optionalName ...string) (string, error)

ReadDoc reads swagger document. An optional name parameter can be passed to read a specific document. The default name is "swagger".

func RefSchema 

func RefSchema(refType string) *spec.Schema

RefSchema build a reference schema.

func Register 

func Register(name string, swagger Swagger)

Register registers swagger for given name.

func SetCodeExampleFilesDirectory 

func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation)

SetCodeExampleFilesDirectory sets the directory to search for codeExamples.

func SetCodeExamplesDirectory 

func SetCodeExamplesDirectory(directoryPath string) func(*Parser)

SetCodeExamplesDirectory sets the directory to search for code example files.

func SetDebugger 

func SetDebugger(logger Debugger) func(parser *Parser)

SetDebugger allows the use of user-defined implementations.

func SetExcludedDirsAndFiles 

func SetExcludedDirsAndFiles(excludes string) func(*Parser)

SetExcludedDirsAndFiles sets directories and files to be excluded when searching.

func SetFieldParserFactory 

func SetFieldParserFactory(factory FieldParserFactory) func(parser *Parser)

SetFieldParserFactory allows the use of user-defined implementations.

func SetMarkdownFileDirectory 

func SetMarkdownFileDirectory(directoryPath string) func(*Parser)

SetMarkdownFileDirectory sets the directory to search for markdown files.

func SetStrict 

func SetStrict(strict bool) func(*Parser)

SetStrict sets whether swag should error or warn when it detects cases which are most likely user errors.

func TransToValidCollectionFormat 

func TransToValidCollectionFormat(format string) string

TransToValidCollectionFormat determine valid collection format.

func TransToValidSchemeType 

func TransToValidSchemeType(typeName string) string

TransToValidSchemeType indicates type will transfer golang basic type to swagger supported type.

func TypeDocName 

func TypeDocName(pkgName string, spec *ast.TypeSpec) string

TypeDocName get alias from comment '// @name ', otherwise the original type name to display in doc.

Types

type AstFileInfo 

type AstFileInfo struct {
	// File ast.File
	File *ast.File

	// Path the path of the ast.File
	Path string

	// PackagePath package import path of the ast.File
	PackagePath string
}

AstFileInfo information of an ast.File.

type Debugger 

type Debugger interface {
	Printf(format string, v ...interface{})
}

Debugger is the interface that wraps the basic Printf method.

type FieldParser 

type FieldParser interface {
	ShouldSkip() (bool, error)
	FieldName() (string, error)
	CustomSchema() (*spec.Schema, error)
	ComplementSchema(schema *spec.Schema) error
	IsRequired() (bool, error)
}

FieldParser parse struct field

type FieldParserFactory 

type FieldParserFactory func(ps *Parser, field *ast.Field) FieldParser

FieldParserFactory create FieldParser

type Formater 

type Formater struct {
	// contains filtered or unexported fields
}

Formater implements a formater for Go source files.

func NewFormater 

func NewFormater() *Formater

NewFormater create a new formater

func (*Formater) FormatAPI 

func (f *Formater) FormatAPI(searchDir, excludeDir, mainFile string) error

FormatAPI format the swag comment.

func (*Formater) FormatFile 

func (f *Formater) FormatFile(filepath string) error

FormatFile format the swag comment in go function.

func (*Formater) FormatMain 

func (f *Formater) FormatMain(mainFilepath string) error

FormatMain format the main.go comment

type Operation 

type Operation struct {
	spec.Operation
	RouterProperties []RouteProperties
	// contains filtered or unexported fields
}

Operation describes a single API operation on a path. For more information: https://github.com/swaggo/swag#api-operation

func NewOperation 

func NewOperation(parser *Parser, options ...func(*Operation)) *Operation

NewOperation creates a new Operation with default properties. map[int]Response.

func (*Operation) AddResponse 

func (operation *Operation) AddResponse(code int, response *spec.Response)

AddResponse add a response for a code.

func (*Operation) DefaultResponse 

func (operation *Operation) DefaultResponse() *spec.Response

DefaultResponse return the default response member pointer.

func (*Operation) ParseAcceptComment 

func (operation *Operation) ParseAcceptComment(commentLine string) error

ParseAcceptComment parses comment for given `accept` comment string.

func (*Operation) ParseCodeSample 

func (operation *Operation) ParseCodeSample(attribute, _, lineRemainder string) error

ParseCodeSample godoc.

func (*Operation) ParseComment 

func (operation *Operation) ParseComment(comment string, astFile *ast.File) error

ParseComment parses comment for given comment string and returns error if error occurs.

func (*Operation) ParseDescriptionComment 

func (operation *Operation) ParseDescriptionComment(lineRemainder string)

ParseDescriptionComment godoc.

func (*Operation) ParseEmptyResponseComment 

func (operation *Operation) ParseEmptyResponseComment(commentLine string) error

ParseEmptyResponseComment parse only comment out status code and description,eg: @Success 200 "it's ok".

func (*Operation) ParseEmptyResponseOnly 

func (operation *Operation) ParseEmptyResponseOnly(commentLine string) error

ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200.

func (*Operation) ParseMetadata 

func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error

ParseMetadata godoc.

func (*Operation) ParseParamComment 

func (operation *Operation) ParseParamComment(commentLine string, astFile *ast.File) error

ParseParamComment parses params return []string of param properties E.g. @Param queryText formData string true "The email for login" 

[param name]    [paramType] [data type]  [is mandatory?]   [Comment]

E.g. @Param some_id path int true "Some ID".

func (*Operation) ParseProduceComment 

func (operation *Operation) ParseProduceComment(commentLine string) error

ParseProduceComment parses comment for given `produce` comment string.

func (*Operation) ParseResponseComment 

func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error

ParseResponseComment parses comment for given `response` comment string.

func (*Operation) ParseResponseHeaderComment 

func (operation *Operation) ParseResponseHeaderComment(commentLine string, _ *ast.File) error

ParseResponseHeaderComment parses comment for given `response header` comment string.

func (*Operation) ParseRouterComment 

func (operation *Operation) ParseRouterComment(commentLine string) error

ParseRouterComment parses comment for given `router` comment string.

func (*Operation) ParseSecurityComment 

func (operation *Operation) ParseSecurityComment(commentLine string) error

ParseSecurityComment parses comment for given `security` comment string.

func (*Operation) ParseTagsComment 

func (operation *Operation) ParseTagsComment(commentLine string)

ParseTagsComment parses comment for given `tag` comment string.

type PackageDefinitions 

type PackageDefinitions struct {
	// files in this package, map key is file's relative path starting package path
	Files map[string]*ast.File

	// definitions in this package, map key is typeName
	TypeDefinitions map[string]*TypeSpecDef

	// package name
	Name string
}

PackageDefinitions files and definition in a package.

type PackagesDefinitions 

type PackagesDefinitions struct {
	// contains filtered or unexported fields
}

PackagesDefinitions map[package import path]*PackageDefinitions.

func NewPackagesDefinitions 

func NewPackagesDefinitions() *PackagesDefinitions

NewPackagesDefinitions create object PackagesDefinitions.

func (*PackagesDefinitions) CollectAstFile 

func (pkgs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File) error

CollectAstFile collect ast.file.

func (*PackagesDefinitions) FindTypeSpec 

func (pkgs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File, parseDependency bool) *TypeSpecDef

FindTypeSpec finds out TypeSpecDef of a type by typeName @typeName the name of the target type, if it starts with a package name, find its own package path from imports on top of @file @file the ast.file in which @typeName is used @pkgPath the package path of @file.

func (*PackagesDefinitions) ParseTypes 

func (pkgs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)

ParseTypes parse types @Return parsed definitions.

func (*PackagesDefinitions) RangeFiles 

func (pkgs *PackagesDefinitions) RangeFiles(handle func(filename string, file *ast.File) error) error

RangeFiles for range the collection of ast.File in alphabetic order.

type Parser 

type Parser struct {

	// PropNamingStrategy naming strategy
	PropNamingStrategy string

	// ParseVendor parse vendor folder
	ParseVendor bool

	// ParseDependencies whether swag should be parse outside dependency folder
	ParseDependency bool

	// ParseInternal whether swag should parse internal packages
	ParseInternal bool

	// Strict whether swag should error or warn when it detects cases which are most likely user errors
	Strict bool
	// contains filtered or unexported fields
}

Parser implements a parser for Go source files.

func New 

func New(options ...func(*Parser)) *Parser

New creates a new Parser with default properties.

func (*Parser) GetSchemaTypePath 

func (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string

GetSchemaTypePath get path of schema type.

func (*Parser) GetSwagger 

func (parser *Parser) GetSwagger() *spec.Swagger

GetSwagger returns *spec.Swagger which is the root document object for the API specification.

func (*Parser) ParseAPI 

func (parser *Parser) ParseAPI(searchDir string, mainAPIFile string, parseDepth int) error

ParseAPI parses general api info for given searchDir and mainAPIFile.

func (*Parser) ParseAPIMultiSearchDir 

func (parser *Parser) ParseAPIMultiSearchDir(searchDirs []string, mainAPIFile string, parseDepth int) error

ParseAPIMultiSearchDir is like ParseAPI but for multiple search dirs.

func (*Parser) ParseAcceptComment 

func (parser *Parser) ParseAcceptComment(commentLine string) error

ParseAcceptComment parses comment for given `accept` comment string.

func (*Parser) ParseDefinition 

func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)

ParseDefinition parses given type spec that corresponds to the type under given name and package, and populates swagger schema definitions registry with a schema for the given type

func (*Parser) ParseGeneralAPIInfo 

func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error

ParseGeneralAPIInfo parses general api info for given mainAPIFile path.

func (*Parser) ParseProduceComment 

func (parser *Parser) ParseProduceComment(commentLine string) error

ParseProduceComment parses comment for given `produce` comment string.

func (*Parser) ParseRouterAPIInfo 

func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error

ParseRouterAPIInfo parses router api info for given astFile.

func (*Parser) Skip 

func (parser *Parser) Skip(path string, f os.FileInfo) error

Skip returns filepath.SkipDir error if match vendor and hidden folder.

type RouteProperties 

type RouteProperties struct {
	HTTPMethod string
	Path       string
}

RouteProperties describes HTTP properties of a single router comment.

type Schema 

type Schema struct {
	*spec.Schema        //
	PkgPath      string // package import path used to rename Name of a definition int case of conflict
	Name         string // Name in definitions
}

Schema parsed schema.

type Swagger 

type Swagger interface {
	ReadDoc() string
}

Swagger is an interface to read swagger document.

type TypeSpecDef 

type TypeSpecDef struct {
	// ast file where TypeSpec is
	File *ast.File

	// the TypeSpec of this type definition
	TypeSpec *ast.TypeSpec

	// path of package starting from under ${GOPATH}/src or from module path in go.mod
	PkgPath string
}

TypeSpecDef the whole information of a typeSpec.

func (*TypeSpecDef) FullName 

func (t *TypeSpecDef) FullName() string

FullName full name of the typeSpec.

func (*TypeSpecDef) Name 

func (t *TypeSpecDef) Name() string

Name the name of the typeSpec.

Source Files

View all Source files

Directories

Path Synopsis
cmd
action-swag command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.