swag

package module
v1.16.5 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2024 License: MIT Imports: 28 Imported by: 4

README

swag

🌍 English ∙ 简体中文 ∙ Português

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

Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).

Contents

Getting started

  1. Add comments to your API source code, See Declarative Comments Format.

  2. Install swag by using:

go install github.com/xu/swag/cmd/swag@latest

To build from source you need Go (1.19 or newer).

Alternatively you can run the docker image:

docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest

Or download a pre-compiled binary from the release page.

  1. Run swag init in the project's root folder which contains the main.go file. This will parse your comments and generate the required files (docs folder and docs/docs.go).
swag init

Make sure to import the generated docs/docs.go so that your specific configuration gets init'ed. If your General API annotations do not live in main.go, you can let swag know with -g flag.

import _ "example-module-name/docs"

swag init -g http/api.go
  1. (optional) Use swag fmt format the SWAG comment. (Please upgrade to the latest version)
swag fmt

swag cli

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

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

OPTIONS:
   --quiet, -q                            Make the logger quiet. (default: false)
   --generalInfo value, -g value          Go file path in which 'swagger general API Info' is written (default: "main.go")
   --dir value, -d value                  Directories you want to parse,comma separated and general-info file must be in the first one (default: "./")
   --exclude value                        Exclude directories and files when searching, comma separated
   --propertyStrategy value, -p value     Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
   --output value, -o value               Output directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: "./docs")
   --outputTypes value, --ot value        Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: "go,json,yaml")
   --parseVendor                          Parse go files in 'vendor' folder, disabled by default (default: false)
   --parseDependency, --pd                Parse go files inside dependency folder, disabled by default (default: false)
   --markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default
   --codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
   --parseInternal                        Parse go files in internal packages, disabled by default (default: false)
   --generatedTime                        Generate timestamp at the top of docs.go, disabled by default (default: false)
   --parseDepth value                     Dependency parse depth (default: 100)
   --requiredByDefault                    Set validation required for all fields by default (default: false)
   --instanceName value                   This parameter can be used to name different swagger document instances. It is optional.
   --overridesFile value                  File to read global type overrides from. (default: ".swaggo")
   --parseGoList                          Parse dependency via 'go list' (default: true)
   --tags value, -t value                 A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded
   --templateDelims value, --td value     Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
   --collectionFormat value, --cf value   Set default collection format (default: "csv")
   --state value                          Initial state for the state machine (default: ""), @HostState in root file, @State in other files
   --parseFuncBody                        Parse API info within body of functions in go files, disabled by default (default: false)
   --help, -h                             show help (default: false)

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

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

OPTIONS:
   --dir value, -d value          Directories you want to parse,comma separated and general-info file must be in the first one (default: "./")
   --exclude value                Exclude directories and files when searching, comma separated
   --generalInfo value, -g value  Go file path in which 'swagger general API Info' is written (default: "main.go")
   --help, -h                     show help (default: false)

Supported Web Frameworks

How to use it with Gin

Find the example source code here.

Finish the steps in Getting started

  1. After using swag init to generate Swagger 2.0 docs, import the following packages:
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
  1. Add General API annotations in main.go code:
// @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

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
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")
}
//...

Additionally some general API info can be set dynamically. The generated code package docs exports SwaggerInfo variable which we can use to set the title, description, version, host and base path programmatically. Example using 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() {

	// programmatically 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. Add API Operation annotations in controller code
package controller

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

    "github.com/gin-gonic/gin"
    "github.com/xu/swag/example/celler/httputil"
    "github.com/xu/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)
}
//...

swag init
  1. Run your app, and browse to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as shown below:

swagger_index.html

The swag formatter

The Swag Comments can be automatically formatted, just like 'go fmt'. Find the result of formatting here.

Usage:

swag fmt

Exclude folder：

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

When using swag fmt, you need to ensure that you have a doc comment for the function to ensure correct formatting. This is due to swag fmt indenting swag comments with tabs, which is only allowed after a standard doc comment.

For example, use

// ListAccounts lists all existing accounts
//
//  @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) {

Implementation Status

Swagger 2.0 document

  • 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

Declarative Comments Format

General API Info

Example celler/main.go

annotation description example
title Required. The title of the application. // @title Swagger Example API
version Required. Provides the version of the application API. // @version 1.0
description A short description of the application. // @description This is a sample server celler server.
tag.name Name of a tag. // @tag.name This is the name of the tag
tag.description Description of the tag // @tag.description Cool Description
tag.docs.url Url of the external Documentation of the tag // @tag.docs.url https://example.com
tag.docs.description Description of the external Documentation of the tag // @tag.docs.description Best example documentation
termsOfService The Terms of Service for the API. // @termsOfService http://swagger.io/terms/
contact.name The contact information for the exposed API. // @contact.name API Support
contact.url The URL pointing to the contact information. MUST be in the format of a URL. // @contact.url http://www.swagger.io/support
contact.email The email address of the contact person/organization. MUST be in the format of an email address. // @contact.email support@swagger.io
license.name Required. The license name used for the API. // @license.name Apache 2.0
license.url A URL to the license used for the API. MUST be in the format of a URL. // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host The host (name or ip) serving the API. // @host localhost:8080
BasePath The base path on which the API is served. // @BasePath /api/v1
accept A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types. // @accept json
produce A list of MIME types the APIs can produce. Value MUST be as described under Mime Types. // @produce json
query.collection.format The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default. // @query.collection.format multi
schemes The transfer protocol for the operation that separated by spaces. // @schemes http https
externalDocs.description Description of the external document. // @externalDocs.description OpenAPI
externalDocs.url URL of the external document. // @externalDocs.url https://swagger.io/resources/open-api/
x-name The extension key, must be start by x- and take only json value // @x-example-key {"key": "value"}
Using markdown descriptions

When a short string in your documentation is insufficient, or you need images, code examples and things like that you may want to use markdown descriptions. In order to use markdown descriptions use the following annotations.

annotation description example
title Required. The title of the application. // @title Swagger Example API
version Required. Provides the version of the application API. // @version 1.0
description.markdown A short description of the application. Parsed from the api.md file. This is an alternative to @description // @description.markdown No value needed, this parses the description from api.md
tag.name Name of a tag. // @tag.name This is the name of the tag
tag.description.markdown Description of the tag this is an alternative to tag.description. The description will be read from a file named like tagname.md // @tag.description.markdown

API Operation

Example celler/controller

annotation description
description A verbose explanation of the operation behavior.
description.markdown A short description of the application. The description will be read from a file. E.g. @description.markdown details will load details.md
id A unique string used to identify the operation. Must be unique among all API operations.
tags A list of tags to each API operation that separated by commas.
summary A short summary of what the operation does.
accept A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types.
produce A list of MIME types the APIs can produce. Value MUST be as described under Mime Types.
param Parameters that separated by spaces. param name,param type,data type,is mandatory?,comment attribute(optional)
security Security to each API operation.
success Success response that separated by spaces. return code or default,{param type},data type,comment
failure Failure response that separated by spaces. return code or default,{param type},data type,comment
response As same as success and failure
header Header in response that separated by spaces. return code,{param type},data type,comment
router Path definition that separated by spaces. path,[httpMethod]
deprecatedrouter As same as router, but deprecated.
x-name The extension key, must be start by x- and take only json value.
x-codeSample Optional Markdown usage. take file as parameter. This will then search for a file named like the summary in the given folder.
deprecated Mark endpoint as deprecated.

Mime Types

swag accepts all MIME Types which are in the correct format, that is, match */*. Besides that, swag also accepts aliases for some MIME Types as follows:

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

Param Type

  • query
  • path
  • header
  • body
  • formData

Data Type

  • string (string)
  • integer (int, uint, uint32, uint64)
  • number (float32)
  • boolean (bool)
  • file (param data type when uploading)
  • user defined struct

Security

annotation description parameters example
securitydefinitions.basic Basic auth. // @securityDefinitions.basic BasicAuth
securitydefinitions.apikey API key auth. in, name, description // @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application OAuth2 application auth. tokenUrl, scope, description // @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit OAuth2 implicit auth. authorizationUrl, scope, description // @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password OAuth2 password auth. tokenUrl, scope, description // @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode OAuth2 access code auth. tokenUrl, authorizationUrl, scope, description // @securitydefinitions.oauth2.accessCode OAuth2AccessCode
parameters annotation example
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
description // @description OAuth protects our entity endpoints

Attribute

// @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   example     query     string     false  "string example"     example(string)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

It also works for the struct fields:

type Foo struct {
    Bar string `minLength:"4" maxLength:"16" example:"random string"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux []string `enums:"foo,bar,baz"`
}
Available
Field Name Type Description
validate string Determines the validation for the parameter. Possible values are: required,optional.
default * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter.
maximum number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
multipleOf number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
maxLength integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums [*] See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
format string The extending format for the previously mentioned type. See Data Type Formats for further details.
collectionFormat string Determines the format of the array if type array is used. Possible values are:
  • csv - comma separated values foo,bar.
  • ssv - space separated values foo bar.
  • tsv - tab separated values foo\tbar.
  • pipes - pipe separated values foo|bar.
  • multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData".
Default value is csv.
example * Declares the example for the parameter value
extensions string Add extension to parameters.
Future
Field Name Type Description
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.

Examples

Descriptions over multiple lines

You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:

// @description This is the first line
// @description This is the second line
// @description And so forth.
User defined structure with an array type
// @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"`
}
Function scoped struct declaration

You can declare your request response structs inside a function body. You must have to follow the naming convention <package-name>.<function-name>.<struct-name> .

package main

// @Param request body main.MyHandler.request true "query params"
// @Success 200 {object} main.MyHandler.response
// @Router /test [post]
func MyHandler() {
	type request struct {
		RequestField string
	}

	type response struct {
		ResponseField string
	}
}
Model composition in response
// JSONResult's data field will be overridden by the specific type 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
    Id  uint            `json:"id"`
    Data  interface{}   `json:"data"`
}
  • also support array of objects and primitive types as nested response
@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"
  • overriding multiple fields. field will be added if not exists
@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
  • overriding deep-level fields
type DeepObject struct { //in `proto` package
	...
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"
Add a headers in response
// @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"
Use multiple path params
/// ...
// @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]
Add multiple paths
/// ...
// @Param group_id path int true "Group ID"
// @Param user_id  path int true "User ID"
// ...
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
// @Router /examples/user/{user_id}/address [put]
Example value of struct
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"`
}
SchemaExample of body
// @Param email body string true "message/rfc822" SchemaExample(Subject: Testmail\r\n\r\nBody Message\r\n)
Description of struct
// Account model info
// @Description User account information
// @Description with user id and username
type Account struct {
	// ID this is userid
	ID   int    `json:"id"`
	Name string `json:"name"` // This is Name
}

#708 The parser handles only struct comments starting with @Description attribute. But it writes all struct field comments as is.

So, generated swagger doc as follows:

"Account": {
  "type":"object",
  "description": "User account information with user id and username"
  "properties": {
    "id": {
      "type": "integer",
      "description": "ID this is userid"
    },
    "name": {
      "type":"string",
      "description": "This is Name"
    }
  }
}
Use swaggertype tag to supported custom type

#201

type TimestampTime struct {
    time.Time
}

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

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 {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    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=="`
}

generated swagger doc as follows:

"api.MyBinding": {
  "type":"object",
  "properties":{
    "crt":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    },
    "key":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    }
  }
}
Use global overrides to support a custom type

If you are using generated files, the swaggertype or swaggerignore tags may not be possible.

By passing a mapping to swag with --overridesFile you can tell swag to use one type in place of another wherever it appears. By default, if a .swaggo file is present in the current directory it will be used.

Go code:

type MyStruct struct {
  ID     sql.NullInt64 `json:"id"`
  Name   sql.NullString `json:"name"`
}

.swaggo:

// Replace all NullInt64 with int
replace database/sql.NullInt64 int

// Don't include any fields of type database/sql.NullString in the swagger docs
skip    database/sql.NullString

Possible directives are comments (beginning with //), replace path/to/a.type path/to/b.type, and skip path/to/a.type.

(Note that the full paths to any named types must be provided to prevent problems when multiple packages define a type with the same name)

Rendered:

"types.MyStruct": {
  "id": "integer"
}
Use swaggerignore tag to exclude a field
type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}
Add extension info to struct field
type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}

generate swagger doc as follows:

"Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def",
            "x-omitempty": false
        }
    }
}
Rename model to display
type Resp struct {
	Code int
}//@name Response
How to use security annotations

General API info.

// @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

Each API operation.

// @Security ApiKeyAuth

Make it AND condition

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

Make it OR condition

// @Security ApiKeyAuth || firebase
// @Security OAuth2Application[write, admin] || APIKeyAuth
Add a description for enum items
type Example struct {
	// Sort order:
	// * asc - Ascending, from A to Z.
	// * desc - Descending, from Z to A.
	Order string `enums:"asc,desc"`
}
Generate only specific docs file types

By default swag command generates Swagger specification in three different files/file types:

  • docs.go
  • swagger.json
  • swagger.yaml

If you would like to limit a set of file types which should be generated you can use --outputTypes (short -ot) flag. Default value is go,json,yaml - output types separated with comma. To limit output only to go and yaml files, you would write go,yaml. With complete command that would be swag init --outputTypes go,yaml.

How to use Generics
// @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
func GetPosts(w http.ResponseWriter, r *http.Request) {
	_ = web.GenericNestedResponse[types.Post]{}
}

See this file for more details and other examples.

Change the default Go Template action delimiters

#980 #1177

If your swagger annotations or struct fields contain "{{" or "}}", the template generation will most likely fail, as these are the default delimiters for go templates.

To make the generation work properly, you can change the default delimiters with -td. For example:

swag init -g http/api.go -td "[[,]]"

The new delimiter is a string with the format "<left delimiter>,<right delimiter>".

About the Project

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.

Contributors

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

Backers

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

Sponsors

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/xu/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 (
	// ParseNone parse nothing
	ParseNone ParseFlag = 0x00
	// ParseModels parse models
	ParseModels = 0x01
	// ParseOperations parse operations
	ParseOperations = 0x02
	// ParseAll parse operations and models
	ParseAll = ParseOperations | ParseModels
)
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"
	// ERROR represent a error value.
	ERROR = "error"
	// INTERFACE represent a interface value.
	INTERFACE = "interface{}"
	// ANY represent a any value.
	ANY = "any"
	// NIL represent a empty value.
	NIL = "nil"

	// IgnoreNameOverridePrefix Prepend to model to avoid renaming based on comment.
	IgnoreNameOverridePrefix = '$'
)
View Source 
const Name = "swagger"

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

View Source 
const Version = "v1.16.3"

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")

	// ErrSkippedField .swaggo specifies field should be skipped.
	ErrSkippedField = errors.New("field is skipped by global overrides")
)

Functions

func BuildCustomSchema added in v1.16.4 

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

BuildCustomSchema build custom schema specified by tag swaggertype.

func CheckSchemaType added in v1.1.1 

func CheckSchemaType(typeName string) error

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

func EvaluateBinary added in v1.16.4 

func EvaluateBinary(x, y interface{}, operator token.Token, xtype, ytype ast.Expr) (interface{}, ast.Expr)

EvaluateBinary evaluate the type and value of a binary expression

func EvaluateDataConversion added in v1.16.4 

func EvaluateDataConversion(x interface{}, typeName string) interface{}

EvaluateDataConversion evaluate the type a explicit type conversion

func EvaluateEscapedChar added in v1.16.4 

func EvaluateEscapedChar(text string) rune

EvaluateEscapedChar parse escaped character

func EvaluateEscapedString added in v1.16.4 

func EvaluateEscapedString(text string) string

EvaluateEscapedString parse escaped characters in string

func EvaluateUnary added in v1.16.4 

func EvaluateUnary(x interface{}, operator token.Token, xtype ast.Expr) (interface{}, ast.Expr)

EvaluateUnary evaluate the type and value of a unary expression

func FieldsByAnySpace added in v1.16.4 

func FieldsByAnySpace(s string, n int) []string

FieldsByAnySpace split a string s by any space character into max n parts

func FieldsFunc added in v1.16.4 

func FieldsFunc(s string, f func(rune2 rune) bool, n int) []string

FieldsFunc split a string s by a func splitter into max n parts

func IsComplexSchema added in v1.16.4 

func IsComplexSchema(schema *spec.Schema) bool

IsComplexSchema whether a schema is complex and should be a ref schema

func IsGolangPrimitiveType added in v1.4.0 

func IsGolangPrimitiveType(typeName string) bool

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

func IsInterfaceLike added in v1.16.4 

func IsInterfaceLike(typeName string) bool

IsInterfaceLike determines whether the swagger type name is an go named interface type like error type.

func IsNumericType added in v1.16.4 

func IsNumericType(typeName string) bool

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

func IsPrimitiveType added in v1.4.0 

func IsPrimitiveType(typeName string) bool

IsPrimitiveType determine whether the type name is a primitive type.

func IsRefSchema added in v1.16.4 

func IsRefSchema(schema *spec.Schema) bool

IsRefSchema whether a schema is a reference schema.

func IsSimplePrimitiveType added in v1.16.4 

func IsSimplePrimitiveType(typeName string) bool

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

func MergeSchema added in v1.16.4 

func MergeSchema(dst *spec.Schema, src *spec.Schema) *spec.Schema

MergeSchema merge schemas

func ParseUsingGoList added in v1.16.4 

func ParseUsingGoList(enabled bool) func(parser *Parser)

ParseUsingGoList sets whether swag use go list to parse dependency

func PrimitiveSchema added in v1.16.4 

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 added in v1.16.4 

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 added in v1.16.4 

func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation)

SetCodeExampleFilesDirectory sets the directory to search for codeExamples.

func SetCodeExamplesDirectory added in v1.16.4 

func SetCodeExamplesDirectory(directoryPath string) func(*Parser)

SetCodeExamplesDirectory sets the directory to search for code example files.

func SetCollectionFormat added in v1.16.4 

func SetCollectionFormat(collectionFormat string) func(*Parser)

SetCollectionFormat set default collection format

func SetDebugger added in v1.16.4 

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

SetDebugger allows the use of user-defined implementations.

func SetExcludedDirsAndFiles added in v1.16.4 

func SetExcludedDirsAndFiles(excludes string) func(*Parser)

SetExcludedDirsAndFiles sets directories and files to be excluded when searching.

func SetFieldParserFactory added in v1.16.4 

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

SetFieldParserFactory allows the use of user-defined implementations.

func SetMarkdownFileDirectory added in v1.16.4 

func SetMarkdownFileDirectory(directoryPath string) func(*Parser)

SetMarkdownFileDirectory sets the directory to search for markdown files.

func SetOverrides added in v1.16.4 

func SetOverrides(overrides map[string]string) func(parser *Parser)

SetOverrides allows the use of user-defined global type overrides.

func SetPackagePrefix added in v1.16.4 

func SetPackagePrefix(packagePrefix string) func(*Parser)

SetPackagePrefix sets a list of package path prefixes from a comma-separated string, packages that do not match any one of them will be excluded when searching.

func SetParseDependency added in v1.16.4 

func SetParseDependency(parseDependency int) func(*Parser)

SetParseDependency sets whether to parse the dependent packages.

func SetParseExtension added in v1.16.4 

func SetParseExtension(parseExtension string) func(*Parser)

SetParseExtension parses only those operations which match given extension

func SetStrict added in v1.16.4 

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 SetTags added in v1.16.4 

func SetTags(include string) func(*Parser)

SetTags sets the tags to be included

func TransToValidCollectionFormat added in v1.16.4 

func TransToValidCollectionFormat(format string) string

TransToValidCollectionFormat determine valid collection format.

func TransToValidSchemeType added in v1.1.1 

func TransToValidSchemeType(typeName string) string

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

Types

type AstFileInfo added in v1.16.4 

type AstFileInfo struct {
	//FileSet the FileSet object which is used to parse this go source file
	FileSet *token.FileSet

	// 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

	// ParseFlag determine what to parse
	ParseFlag ParseFlag
}

AstFileInfo information of an ast.File.

type ConstVariable added in v1.16.4 

type ConstVariable struct {
	Name    *ast.Ident
	Type    ast.Expr
	Value   interface{}
	Comment *ast.CommentGroup
	File    *ast.File
	Pkg     *PackageDefinitions
}

ConstVariable a model to record a const variable

type ConstVariableGlobalEvaluator added in v1.16.4 

type ConstVariableGlobalEvaluator interface {
	EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr)
	EvaluateConstValueByName(file *ast.File, pkgPath, constVariableName string, recursiveStack map[string]struct{}) (interface{}, ast.Expr)
	FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef
}

ConstVariableGlobalEvaluator an interface used to evaluate enums across packages

type Debugger added in v1.16.4 

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

Debugger is the interface that wraps the basic Printf method.

type EnumValue added in v1.16.4 

type EnumValue struct {
	Value   interface{}
	Comment string
	// contains filtered or unexported fields
}

EnumValue a model to record an enum consts variable

type FieldParser added in v1.16.4 

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

FieldParser parse struct field.

type FieldParserFactory added in v1.16.4 

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

FieldParserFactory create FieldParser.

type Formatter added in v1.16.4 

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

Formatter implements a formatter for Go source files.

func NewFormatter added in v1.16.4 

func NewFormatter() *Formatter

NewFormatter create a new formatter instance.

func (*Formatter) Format added in v1.16.4 

func (f *Formatter) Format(fileName string, contents []byte) ([]byte, error)

Format formats swag comments in contents. It uses fileName to report errors that happen during parsing of contents.

type Operation 

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

Operation describes a single API operation on a path. For more information: https://github.com/xu/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 added in v1.16.4 

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

AddResponse add a response for a code.

func (*Operation) DefaultResponse added in v1.16.4 

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 added in v1.16.4 

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

ParseCodeSample parse code sample.

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 added in v1.16.4 

func (operation *Operation) ParseDescriptionComment(lineRemainder string)

ParseDescriptionComment parse description comment.

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 added in v1.4.0 

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

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

func (*Operation) ParseMetadata added in v1.16.4 

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

ParseMetadata parse metadata.

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 added in v1.16.4 

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, deprecated bool) error

ParseRouterComment parses comment for given `router` comment string.

func (*Operation) ParseSecurityComment added in v1.3.2 

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

ParseSecurityComment parses comment for given `security` comment string.

func (*Operation) ParseStateComment added in v1.16.4 

func (operation *Operation) ParseStateComment(lineRemainder string)

ParseStateComment parse state comment.

func (*Operation) ParseTagsComment added in v1.1.0 

func (operation *Operation) ParseTagsComment(commentLine string)

ParseTagsComment parses comment for given `tag` comment string.

type PackageDefinitions added in v1.16.4 

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

	// const variables in this package, map key is the name
	ConstTable map[string]*ConstVariable

	// const variables in order in this package
	OrderedConst []*ConstVariable

	// package name
	Name string

	// package path
	Path string
}

PackageDefinitions files and definition in a package.

func NewPackageDefinitions added in v1.16.4 

func NewPackageDefinitions(name, pkgPath string) *PackageDefinitions

NewPackageDefinitions new a PackageDefinitions object

func (*PackageDefinitions) AddConst added in v1.16.4 

func (pkg *PackageDefinitions) AddConst(astFile *ast.File, valueSpec *ast.ValueSpec) *PackageDefinitions

AddConst add a const variable.

func (*PackageDefinitions) AddFile added in v1.16.4 

func (pkg *PackageDefinitions) AddFile(pkgPath string, file *ast.File) *PackageDefinitions

AddFile add a file

func (*PackageDefinitions) AddTypeSpec added in v1.16.4 

func (pkg *PackageDefinitions) AddTypeSpec(name string, typeSpec *TypeSpecDef) *PackageDefinitions

AddTypeSpec add a type spec.

type PackagesDefinitions added in v1.16.4 

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

PackagesDefinitions map[package import path]*PackageDefinitions.

func NewPackagesDefinitions added in v1.16.4 

func NewPackagesDefinitions() *PackagesDefinitions

NewPackagesDefinitions create object PackagesDefinitions.

func (*PackagesDefinitions) EvaluateConstValue added in v1.16.4 

func (pkgDefs *PackagesDefinitions) EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr)

EvaluateConstValue evaluate a const variable.

func (*PackagesDefinitions) EvaluateConstValueByName added in v1.16.4 

func (pkgDefs *PackagesDefinitions) EvaluateConstValueByName(file *ast.File, pkgName, constVariableName string, recursiveStack map[string]struct{}) (interface{}, ast.Expr)

EvaluateConstValueByName evaluate a const variable by name.

func (*PackagesDefinitions) FindTypeSpec added in v1.16.4 

func (pkgDefs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File) *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) ParseFile added in v1.16.4 

func (pkgDefs *PackagesDefinitions) ParseFile(packageDir, path string, src interface{}, flag ParseFlag) error

ParseFile parse a source file.

func (*PackagesDefinitions) ParseTypes added in v1.16.4 

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

ParseTypes parse types @Return parsed definitions.

func (*PackagesDefinitions) RangeFiles added in v1.16.4 

func (pkgDefs *PackagesDefinitions) RangeFiles(handle func(info *AstFileInfo) error) error

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

type ParseFlag added in v1.16.4 

type ParseFlag int

ParseFlag determine what to parse

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: 0 none, 1 models, 2 operations, 3 all
	ParseDependency ParseFlag

	// 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

	// RequiredByDefault set validation required for all fields by default
	RequiredByDefault bool

	// Overrides allows global replacements of types. A blank replacement will be skipped.
	Overrides map[string]string

	// HostState is the state of the host
	HostState string

	// ParseFuncBody whether swag should parse api info inside of funcs
	ParseFuncBody 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 added in v1.16.4 

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 added in v1.3.2 

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

ParseAPI parses general api info for given searchDir and mainAPIFile.

func (*Parser) ParseAPIMultiSearchDir added in v1.16.4 

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

ParseAPIMultiSearchDir is like ParseAPI but for multiple search dirs.

func (*Parser) ParseAcceptComment added in v1.16.4 

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

ParseAcceptComment parses comment for given `accept` comment string.

func (*Parser) ParseDefinition added in v1.1.1 

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 added in v1.3.2 

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

ParseGeneralAPIInfo parses general api info for given mainAPIFile path.

func (*Parser) ParseProduceComment added in v1.16.4 

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

ParseProduceComment parses comment for given `produce` comment string.

func (*Parser) ParseRouterAPIInfo added in v1.3.2 

func (parser *Parser) ParseRouterAPIInfo(fileInfo *AstFileInfo) error

ParseRouterAPIInfo parses router api info for given astFile.

func (*Parser) Skip added in v1.16.4 

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

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

type RouteProperties added in v1.16.4 

type RouteProperties struct {
	HTTPMethod string
	Path       string
	Deprecated bool
}

RouteProperties describes HTTP properties of a single router comment.

type Schema added in v1.16.4 

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 Spec added in v1.16.4 

type Spec struct {
	Version          string
	Host             string
	BasePath         string
	Schemes          []string
	Title            string
	Description      string
	InfoInstanceName string
	SwaggerTemplate  string
	LeftDelim        string
	RightDelim       string
}

Spec holds exported Swagger Info so clients can modify it.

func (*Spec) InstanceName added in v1.16.4 

func (i *Spec) InstanceName() string

InstanceName returns Spec instance name.

func (*Spec) ReadDoc added in v1.16.4 

func (i *Spec) ReadDoc() string

ReadDoc parses SwaggerTemplate into swagger document.

type Swagger 

type Swagger interface {
	ReadDoc() string
}

Swagger is an interface to read swagger document.

func GetSwagger added in v1.16.4 

func GetSwagger(name string) Swagger

GetSwagger returns the swagger instance for given name. If not found, returns nil.

type TypeSpecDef added in v1.16.4 

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

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

	Enums []EnumValue

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

	SchemaName string

	NotUnique bool
}

TypeSpecDef the whole information of a typeSpec.

func (*TypeSpecDef) Alias added in v1.16.4 

func (t *TypeSpecDef) Alias() string

func (*TypeSpecDef) FullPath added in v1.16.4 

func (t *TypeSpecDef) FullPath() string

FullPath return the full path of the typeSpec.

func (*TypeSpecDef) Name added in v1.16.4 

func (t *TypeSpecDef) Name() string

Name the name of the typeSpec.

func (*TypeSpecDef) SetSchemaName added in v1.16.4 

func (t *TypeSpecDef) SetSchemaName()

func (*TypeSpecDef) TypeName added in v1.16.4 

func (t *TypeSpecDef) TypeName() string

TypeName the type name of the typeSpec.

Source Files

View all Source files

Directories

Path Synopsis
cmd
swag
example
basic
basic/api
basic/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
 Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
basic/web
override
override/docs
Package docs GENERATED BY SWAG; DO NOT EDIT This file was generated by swaggo/swag
 Package docs GENERATED BY SWAG; DO NOT EDIT This file was generated by swaggo/swag
celler Module
go-module-support Module
markdown Module
object-map-example Module

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.