+ Encore – the platform for building Go-based cloud backends
+
+
+
+[](https://github.com/features/actions)
+[](https://codecov.io/gh/swaggo/swag)
+[](https://goreportcard.com/report/github.com/swaggo/swag)
+[](https://codebeat.co/projects/github-com-swaggo-swag-master)
+[](https://godoc.org/github.com/swaggo/swag)
+[](#backers)
+[](#sponsors) [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)
+[](https://github.com/swaggo/swag/releases)
+
+
+Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular [Go web frameworks](#supported-web-frameworks). This allows you to quickly integrate with an existing Go project (using Swagger UI).
+
+## Contents
+ - [Getting started](#getting-started)
+ - [Supported Web Frameworks](#supported-web-frameworks)
+ - [How to use it with Gin](#how-to-use-it-with-gin)
+ - [The swag formatter](#the-swag-formatter)
+ - [Implementation Status](#implementation-status)
+ - [Declarative Comments Format](#declarative-comments-format)
+ - [General API Info](#general-api-info)
+ - [API Operation](#api-operation)
+ - [Security](#security)
+ - [Examples](#examples)
+ - [Descriptions over multiple lines](#descriptions-over-multiple-lines)
+ - [User defined structure with an array type](#user-defined-structure-with-an-array-type)
+ - [Function scoped struct declaration](#function-scoped-struct-declaration)
+ - [Model composition in response](#model-composition-in-response)
+ - [Add a headers in response](#add-a-headers-in-response)
+ - [Use multiple path params](#use-multiple-path-params)
+ - [Example value of struct](#example-value-of-struct)
+ - [SchemaExample of body](#schemaexample-of-body)
+ - [Description of struct](#description-of-struct)
+ - [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)
+ - [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)
+ - [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)
+ - [Add extension info to struct field](#add-extension-info-to-struct-field)
+ - [Rename model to display](#rename-model-to-display)
+ - [How to use security annotations](#how-to-use-security-annotations)
+ - [Add a description for enum items](#add-a-description-for-enum-items)
+ - [Generate only specific docs file types](#generate-only-specific-docs-file-types)
+ - [How to use Go generic types](#how-to-use-generics)
+- [About the Project](#about-the-project)
+
+## Getting started
+
+1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).
+
+2. Install swag by using:
+```sh
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+To build from source you need [Go](https://golang.org/dl/) (1.18 or newer).
+
+Alternatively you can run the docker image:
+```sh
+docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest
+```
+
+Or download a pre-compiled binary from the [release page](https://github.com/swaggo/swag/releases).
+
+3. 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`).
+```sh
+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.
+ ```go
+ import _ "example-module-name/docs"
+ ```
+ ```sh
+ swag init -g http/api.go
+ ```
+
+4. (optional) Use `swag fmt` format the SWAG comment. (Please upgrade to the latest version)
+
+ ```sh
+ swag fmt
+ ```
+
+## swag cli
+
+```sh
+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 delimeters 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
+ --help, -h show help (default: false)
+```
+
+```bash
+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
+
+- [gin](http://github.com/swaggo/gin-swagger)
+- [echo](http://github.com/swaggo/echo-swagger)
+- [buffalo](https://github.com/swaggo/buffalo-swagger)
+- [net/http](https://github.com/swaggo/http-swagger)
+- [gorilla/mux](https://github.com/swaggo/http-swagger)
+- [go-chi/chi](https://github.com/swaggo/http-swagger)
+- [flamingo](https://github.com/i-love-flamingo/swagger)
+- [fiber](https://github.com/gofiber/swagger)
+- [atreugo](https://github.com/Nerzal/atreugo-swagger)
+- [hertz](https://github.com/hertz-contrib/swagger)
+
+## How to use it with Gin
+
+Find the example source code [here](https://github.com/swaggo/swag/tree/master/example/celler).
+
+Finish the steps in [Getting started](#getting-started)
+1. After using `swag init` to generate Swagger 2.0 docs, import the following packages:
+```go
+import "github.com/swaggo/gin-swagger" // gin-swagger middleware
+import "github.com/swaggo/files" // swagger embed files
+```
+
+2. Add [General API](#general-api-info) annotations in `main.go` code:
+
+```go
+// @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:
+
+```go
+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()
+}
+```
+
+3. Add [API Operation](#api-operation) annotations in `controller` code
+
+``` go
+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)
+}
+//...
+```
+
+```console
+swag init
+```
+
+4. Run your app, and browse to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as shown below:
+
+
+
+## The swag formatter
+
+The Swag Comments can be automatically formatted, just like 'go fmt'.
+Find the result of formatting [here](https://github.com/swaggo/swag/tree/master/example/celler).
+
+Usage:
+```shell
+swag fmt
+```
+
+Exclude folder：
+```shell
+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
+
+```go
+// 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](https://swagger.io/docs/specification/2-0/basic-structure/)
+
+- [x] Basic Structure
+- [x] API Host and Base Path
+- [x] Paths and Operations
+- [x] Describing Parameters
+- [x] Describing Request Body
+- [x] Describing Responses
+- [x] MIME Types
+- [x] Authentication
+ - [x] Basic Authentication
+ - [x] API Keys
+- [x] Adding Examples
+- [x] File Upload
+- [x] Enums
+- [x] Grouping Operations With Tags
+- [ ] Swagger Extensions
+
+# Declarative Comments Format
+
+## General API Info
+
+**Example**
+[celler/main.go](https://github.com/swaggo/swag/blob/master/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](#mime-types). | // @accept json |
+| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#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](https://github.com/swaggo/swag/tree/master/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` | // @description.file endpoint.description.markdown |
+| 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](#mime-types). |
+| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
+| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
+| security | [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](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth |
+| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth |
+| securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
+| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password |
+| securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) 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
+
+```go
+// @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:
+
+```go
+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`](#parameterType) 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`](#parameterType). See [Data Type Formats](https://swagger.io/specification/v2/#dataTypeFormat) for further details.
+collectionFormat | `string` |Determines the format of the array if type array is used. Possible values are: foo|bar. 
+
+
+## Backers
+
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]
+
+
+
+
+## Sponsors
+
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/swag#sponsor)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## License
+[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)
diff --git a/vendor/github.com/swaggo/swag/README_pt.md b/vendor/github.com/swaggo/swag/README_pt.md
new file mode 100644
index 0000000..7f95066
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/README_pt.md
@@ -0,0 +1,968 @@
+# swag
+
+🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md) ∙ [Português](README_pt.md)*
+
+
+
+[](https://github.com/features/actions)
+[](https://codecov.io/gh/swaggo/swag)
+[](https://goreportcard.com/report/github.com/swaggo/swag)
+[](https://codebeat.co/projects/github-com-swaggo-swag-master)
+[](https://godoc.org/github.com/swaggo/swag)
+[](#backers)
+[](#sponsors) [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)
+[](https://github.com/swaggo/swag/releases)
+
+Swag converte anotações Go para Documentação Swagger 2.0. Criámos uma variedade de plugins para populares [Go web frameworks](#supported-web-frameworks). Isto permite uma integração rápida com um projecto Go existente (utilizando a Swagger UI).
+
+## Conteúdo
+- [Começando](#começando)
+ - [Estruturas Web Suportadas](#estruturas-web-suportadas)
+ - [Como utilizá-lo com Gin](#como-como-ser-como-gin)
+ - [O formatador de swag](#a-formatação-de-swag)
+ - [Estado de Implementação](#implementação-estado)
+ - [Formato dos comentários declarativos](#formato-dos-comentarios-declarativos)
+ - [Informações Gerais API](#informações-gerais-api)
+ - [Operação API](#api-operacao)
+ - [Segurança](#seguranca)
+ - [Exemplos](#exemplos)
+ - [Descrições em múltiplas linhas](#descricoes-sobre-múltiplas-linhas)
+ - [Estrutura definida pelo utilizador com um tipo de matriz](#-estrutura-definida-pelo-utilizador-com-um-um-tipo)
+ - [Declaração de estruturação de funções](#function-scoped-struct-declaration)
+ - [Composição do modelo em resposta](#model-composição-em-resposta)
+ - [Adicionar um cabeçalho em resposta](#add-a-headers-in-response)
+ - [Utilizar parâmetros de caminhos múltiplos](#use-multiple-path-params)
+ - [Exemplo de valor de estrutura](#exemplo-do-valor-de-estrutura)
+ - [Schema Exemplo do corpo](#schemaexample-of-body)
+ - [Descrição da estrutura](#descrição-da-estrutura)
+ - [Usar etiqueta do tipo swaggertype para suportar o tipo personalizado](#use-swaggertype-tag-to-supported-custom-type)
+ - [Utilizar anulações globais para suportar um tipo personalizado](#use-global-overrides-to-support-a-custom-type)
+ - [Use swaggerignore tag para excluir um campo](#use-swaggerignore-tag-to-excluir-um-campo)
+ - [Adicionar informações de extensão ao campo de estruturação](#add-extension-info-to-struct-field)
+ - [Renomear modelo a expor](#renome-modelo-a-exibir)
+ - [Como utilizar as anotações de segurança](#como-utilizar-as-anotações-de-segurança)
+ - [Adicionar uma descrição para enumerar artigos](#add-a-description-for-enum-items)
+ - [Gerar apenas tipos de ficheiros de documentos específicos](#generate-only-specific-docs-file-file-types)
+ - [Como usar tipos genéricos](#como-usar-tipos-genéricos)
+- [Sobre o projecto](#sobre-o-projecto)
+
+## Começando
+
+1. Adicione comentários ao código-fonte da API, consulte [Formato dos comentários declarativos](#declarative-comments-format).
+
+2. Descarregue o swag utilizando:
+```sh
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+Para construir a partir da fonte é necessário [Go](https://golang.org/dl/) (1.18 ou mais recente).
+
+Ou descarregar um binário pré-compilado a partir da [página de lançamento](https://github.com/swaggo/swag/releases).
+
+3. Executar `swag init` na pasta raiz do projecto que contém o ficheiro `main.go`. Isto irá analisar os seus comentários e gerar os ficheiros necessários (pasta `docs` e `docs/docs.go`).
+```sh
+swag init
+```
+
+Certifique-se de importar os `docs/docs.go` gerados para que a sua configuração específica fique "init" ed. Se as suas anotações API gerais não viverem em `main.go`, pode avisar a swag com a bandeira `-g`.
+```sh
+swag init -g http/api.go
+```
+
+4. (opcional) Utilizar o formato `swag fmt` no comentário SWAG. (Por favor, actualizar para a versão mais recente)
+
+```sh
+swag fmt
+```
+
+## swag cli
+
+```sh
+swag init -h
+NOME:
+ swag init - Criar docs.go
+
+UTILIZAÇÃO:
+ swag init [opções de comando] [argumentos...]
+
+OPÇÕES:
+ --quiet, -q Fazer o logger ficar quiet (por padrão: falso)
+ --generalInfo valor, -g valor Go caminho do ficheiro em que 'swagger general API Info' está escrito (por padrão: "main.go")
+ --dir valor, -d valor Os directórios que deseja analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
+ --exclude valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
+ -propertyStrategy da estratégia, -p valor da propriedadeEstratégia de nomeação de propriedades como snakecase,camelcase,pascalcase (por padrão: "camelcase")
+ --output de saída, -o valor directório de saída para todos os ficheiros gerados(swagger.json, swagger.yaml e docs.go) (por padrão: "./docs")
+ --outputTypes valor de saídaTypes, -- valor de saída Tipos de ficheiros gerados (docs.go, swagger.json, swagger.yaml) como go,json,yaml (por padrão: "go,json,yaml")
+ --parseVendor ParseVendor Parse go files na pasta 'vendor', desactivado por padrão (padrão: falso)
+ --parseInternal Parse go ficheiros em pacotes internos, desactivados por padrão (padrão: falso)
+ --generatedTime Gerar timestamp no topo dos docs.go, desactivado por padrão (padrão: falso)
+ --parteDepth value Dependência profundidade parse (por padrão: 100)
+ --templateDelims value, --td value fornecem delimitadores personalizados para a geração de modelos Go. O formato é leftDelim,rightDelim. Por exemplo: "[[,]]"
+ ...
+
+ --help, -h mostrar ajuda (por padrão: falso)
+```
+
+```bash
+swag fmt -h
+NOME:
+ swag fmt - formato swag comentários
+
+UTILIZAÇÃO:
+ swag fmt [opções de comando] [argumentos...]
+
+OPÇÕES:
+ --dir valor, -d valor Os directórios que pretende analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
+ --excluir valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
+ --generalInfo value, -g value Go file path in which 'swagger general API Info' is written (por padrão: "main.go")
+ --ajuda, -h mostrar ajuda (por padrão: falso)
+
+```
+
+## Estruturas Web Suportadas
+
+- [gin](http://github.com/swaggo/gin-swagger)
+- [echo](http://github.com/swaggo/echo-swagger)
+- [buffalo](https://github.com/swaggo/buffalo-swagger)
+- [net/http](https://github.com/swaggo/http-swagger)
+- [gorilla/mux](https://github.com/swaggo/http-swagger)
+- [go-chi/chi](https://github.com/swaggo/http-swagger)
+- [flamingo](https://github.com/i-love-flamingo/swagger)
+- [fiber](https://github.com/gofiber/swagger)
+- [atreugo](https://github.com/Nerzal/atreugo-swagger)
+- [hertz](https://github.com/hertz-contrib/swagger)
+
+## Como utilizá-lo com Gin
+
+Encontrar o código fonte de exemplo [aqui](https://github.com/swaggo/swag/tree/master/example/celler).
+
+1. Depois de utilizar `swag init` para gerar os documentos Swagger 2.0, importar os seguintes pacotes:
+```go
+import "github.com/swaggo/gin-swagger" // gin-swagger middleware
+import "github.com/swaggo/files" // swagger embed files
+```
+
+2. Adicionar [Informações Gerais API](#general-api-info) anotações em código `main.go`:
+
+
+```go
+// @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")
+}
+//...
+```
+
+Além disso, algumas informações API gerais podem ser definidas de forma dinâmica. O pacote de código gerado `docs` exporta a variável `SwaggerInfo` que podemos utilizar para definir programticamente o título, descrição, versão, hospedeiro e caminho base. Exemplo utilizando Gin:
+
+```go
+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()
+}
+```
+
+3. Adicionar [Operação API](#api-operacao) anotações em código `controller`
+
+```go
+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)
+}
+//...
+```
+
+```console
+swag init
+```
+
+4. Execute a sua aplicação, e navegue para http://localhost:8080/swagger/index.html. Verá os documentos Swagger 2.0 Api, como mostrado abaixo:
+
+
+
+## O formatador de swag
+
+Os Swag Comments podem ser formatados automaticamente, assim como 'go fmt'.
+Encontre o resultado da formatação [aqui](https://github.com/swaggo/swag/tree/master/example/celler).
+
+Usage:
+```shell
+swag fmt
+```
+
+Exclude folder：
+```shell
+swag fmt -d ./ --exclude ./internal
+```
+
+Ao utilizar `swag fmt`, é necessário assegurar-se de que tem um comentário doc para a função a fim de assegurar uma formatação correcta.
+Isto deve-se ao `swag fmt` que traça comentários swag com separadores, o que só é permitido *após* um comentário doc padrão.
+
+Por exemplo, utilizar
+
+```go
+// 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) {
+```
+
+## Estado de Implementação
+
+[Documento Swagger 2.0](https://swagger.io/docs/specification/2-0/basic-structure/)
+
+- [x] Estrutura básica
+- [x] Hospedeiro API e Caminho Base
+- [x] Caminhos e operações
+- [x] Descrição dos parâmetros
+- [x] Descrever o corpo do pedido
+- [x] Descrição das respostas
+- [x] Tipos MIME
+- [x] Autenticação
+ - [x] Autenticação básica
+ - [x] Chaves API
+- [x] Acrescentar exemplos
+- [x] Carregamento de ficheiros
+- [x] Enums
+- [x] Operações de Agrupamento com Etiquetas
+- Extensões Swagger
+
+## Formato dos comentários declarativos
+
+## Informações Gerais API
+
+**Exemplo**
+[celler/main.go](https://github.com/swaggo/swag/blob/master/example/celler/main.go)
+
+| anotação | descrição | exemplo |
+|-------------|--------------------------------------------|---------------------------------|
+| title | **Obrigatório.** O título da aplicação.| // @title Swagger Example API |
+| version | **Obrigatório.** Fornece a versão da aplicação API.| // @version 1.0 |
+| description | Uma breve descrição da candidatura. |// @descrição Este é um servidor servidor de celas de amostra. |
+| tag.name | Nome de uma tag.| // @tag.name Este é o nome da tag |
+| tag.description | Descrição da tag | // @tag.description Cool Description |
+| tag.docs.url | Url da Documentação externa da tag | // @tag.docs.url https://example.com|
+| tag.docs.description | Descrição da documentação externa da tag| // @tag.docs.description Melhor exemplo de documentação |
+| TermsOfService | Os Termos de Serviço para o API.| // @termsOfService http://swagger.io/terms/ |
+| contact.name | A informação de contacto para a API exposta.| // @contacto.name Suporte API |
+| contact.url | O URL que aponta para as informações de contacto. DEVE estar no formato de um URL. | // @contact.url http://www.swagger.io/support|
+| contact.email| O endereço de email da pessoa/organização de contacto. DEVE estar no formato de um endereço de correio electrónico.| // @contact.email support@swagger.io |
+| license.name | **Obrigatório.** O nome da licença utilizada para a API.|// @licença.name Apache 2.0|
+| license.url | Um URL para a licença utilizada para a API. DEVE estar no formato de um URL. | // @license.url http://www.apache.org/licenses/LICENSE-2.0.html |
+| host | O anfitrião (nome ou ip) que serve o API. | // @host localhost:8080 |
+| BasePath | O caminho de base sobre o qual o API é servido. | // @BasePath /api/v1 |
+| accept | Uma lista de tipos de MIME que os APIs podem consumir. Note que accept só afecta operações com um organismo de pedido, tais como POST, PUT e PATCH. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). | // @accept json |
+| produce | Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). | // @produce json |
+| query.collection.format | O formato padrão de param de colecção(array) em query,enums:csv,multi,pipes,tsv,ssv. Se não definido, csv é o padrão.| // @query.collection.format multi
+| schemes | O protocolo de transferência para a operação que separou por espaços. | // @schemes http https |
+| externalDocs.description | Descrição do documento externo. | // @externalDocs.description OpenAPI |
+| externalDocs.url | URL do documento externo. | // @externalDocs.url https://swagger.io/resources/open-api/ |
+| x-name | A chave de extensão, deve ser iniciada por x- e tomar apenas o valor json | // @x-example-key {"chave": "valor"} |
+
+### Usando descrições de remarcação para baixo
+Quando uma pequena sequência na sua documentação é insuficiente, ou precisa de imagens, exemplos de códigos e coisas do género, pode querer usar descrições de marcação. Para utilizar as descrições markdown, utilize as seguintes anotações.
+
+| anotação | descrição | exemplo |
+|-------------|--------------------------------------------|---------------------------------|
+| title | **Obrigatório.** O título da aplicação.| // @title Swagger Example API |
+| version | **Obrigatório.** Fornece a versão da aplicação API.| // @versão 1.0 |
+| description.markdown | Uma breve descrição da candidatura. Parsed a partir do ficheiro api.md. Esta é uma alternativa a @description |// @description.markdown Sem valor necessário, isto analisa a descrição do ficheiro api.md |.
+| tag.name | Nome de uma tag.| // @tag.name Este é o nome da tag |
+| tag.description.markdown | Descrição da tag esta é uma alternativa à tag.description. A descrição será lida a partir de um ficheiro nomeado como tagname.md | // @tag.description.markdown |
+
+## Operação API
+
+**Exemplo**
+[celler/controller](https://github.com/swaggo/swag/tree/master/example/celler/controller)
+
+| anotação | descrição |
+|-------------|----------------------------------------------------------------------------------------------------------------------------|
+| descrição | Uma explicação verbosa do comportamento da operação. |
+| description.markdown | Uma breve descrição da candidatura. A descrição será lida a partir de um ficheiro. Por exemplo, `@description.markdown details` irá carregar `details.md`| // @description.file endpoint.description.markdown |
+| id | Um fio único utilizado para identificar a operação. Deve ser única entre todas as operações API. |
+| tags | Uma lista de tags para cada operação API que separou por vírgulas. |
+| summary | Um breve resumo do que a operação faz. |
+| accept | Uma lista de tipos de MIME que os APIs podem consumir. Note que accept só afecta operações com um organismo de pedido, tais como POST, PUT e PATCH. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). |
+| produce | Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). |
+| param | Parâmetros que se separaram por espaços. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
+| security | [Segurança](#security) para cada operação API. |
+| success | resposta de sucesso que separou por espaços. `return code or default`,`{param type}`,`data type`,`comment` |.
+| failure | Resposta de falha que separou por espaços. `return code or default`,`{param type}`,`data type`,`comment` |
+| response | Igual ao `sucesso` e `falha` |
+| header | Cabeçalho em resposta que separou por espaços. `código de retorno`,`{tipo de parâmetro}`,`tipo de dados`,`comentário` |.
+| router | Definição do caminho que separou por espaços. caminho",`path`,`[httpMethod]` |[httpMethod]` |
+| x-name | A chave de extensão, deve ser iniciada por x- e tomar apenas o valor json. |
+| x-codeSample | Optional Markdown use. tomar `file` como parâmetro. Isto irá então procurar um ficheiro nomeado como o resumo na pasta dada. |
+| deprecated | Marcar o ponto final como depreciado. |
+
+## Mime Types
+
+`swag` aceita todos os tipos MIME que estão no formato correcto, ou seja, correspondem `*/*`.
+Além disso, `swag` também aceita pseudónimos para alguns tipos de MIME, como se segue:
+
+
+| 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 |
+
+
+
+## Tipo de parâmetro
+
+- query
+- path
+- header
+- body
+- formData
+
+## Tipo de dados
+
+- string (string)
+- integer (int, uint, uint32, uint64)
+- number (float32)
+- boolean (bool)
+- file (param data type when uploading)
+- user defined struct
+
+## Segurança
+| anotação | descrição | parâmetros | exemplo |
+|------------|-------------|------------|---------|
+| securitydefinitions.basic | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basicAuth | [Básico]()
+| securitydefinitions.apikey | [chave API](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth |
+| securitydefinitions.oauth2.application | [Aplicação OAuth2](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit | [OAuth2Implicit]()
+| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password |
+| securitydefinitions.oauth2.accessCode | [código de acesso OAuth2](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode | [código de acesso OAuth2.accessCode]()
+
+
+| anotação de parâmetros | exemplo |
+|---------------------------------|-------------------------------------------------------------------------|
+| 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 | // @descrição OAuth protege os pontos finais da nossa entidade |
+
+## Atributo
+
+```go
+// @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:
+
+```go
+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"`
+}
+```
+
+### Disponível
+
+Nome do campo | Tipo | Descrição
+---|:---:|---
+validate | `string` | Determina a validação para o parâmetro. Os valores possíveis são: `required,optional`.
+default | * | Declara o valor do parâmetro que o servidor utilizará se nenhum for fornecido, por exemplo, uma "contagem" para controlar o número de resultados por página poderá ser por defeito de 100 se não for fornecido pelo cliente no pedido. (Nota: "por defeito" não tem significado para os parâmetros requeridos).
+See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Ao contrário do esquema JSON, este valor DEVE estar em conformidade com o definido [`type`](#parameterType) para este parâmetro.
+maximum | `number` | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
+minimum | `number` | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
+multipleOf | `number` | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
+maxLength | `integer` | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
+minLength | `integer` | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
+enums | [\*] | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
+format | `string` | O formato de extensão para o anteriormente mencionado [`type`](#parameterType). Ver [Data Type Formats](https://swagger.io/specification/v2/#dataTypeFormat) para mais detalhes.
+collectionFormat | `string` |Determina o formato da matriz se for utilizada uma matriz de tipos. Os valores possíveis são: foo|bar.
+
+
+## Apoios
+
+Obrigado a todos os nossos apoiantes! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]
+
+
+
+
+## Patrocinadores
+
+Apoiar este projecto tornando-se um patrocinador. O seu logótipo aparecerá aqui com um link para o seu website. [[Become a sponsor](https://opencollective.com/swag#sponsor)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Licença
+[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)
diff --git a/vendor/github.com/swaggo/swag/README_zh-CN.md b/vendor/github.com/swaggo/swag/README_zh-CN.md
new file mode 100644
index 0000000..87d600b
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/README_zh-CN.md
@@ -0,0 +1,770 @@
+# swag
+
+🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md)*
+
+
+
+[](https://travis-ci.org/swaggo/swag)
+[](https://codecov.io/gh/swaggo/swag)
+[](https://goreportcard.com/report/github.com/swaggo/swag)
+[](https://codebeat.co/projects/github-com-swaggo-swag-master)
+[](https://godoc.org/github.com/swaggo/swag)
+[](#backers)
+[](#sponsors) [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)
+[](https://github.com/swaggo/swag/releases)
+
+Swag将Go的注释转换为Swagger2.0文档。我们为流行的 [Go Web Framework](#支持的Web框架) 创建了各种插件，这样可以与现有Go项目快速集成（使用Swagger UI）。
+
+## 目录
+
+- [快速开始](#快速开始)
+- [支持的Web框架](#支持的web框架)
+- [如何与Gin集成](#如何与gin集成)
+- [格式化说明](#格式化说明)
+- [开发现状](#开发现状)
+- [声明式注释格式](#声明式注释格式)
+ - [通用API信息](#通用api信息)
+ - [API操作](#api操作)
+ - [安全性](#安全性)
+- [样例](#样例)
+ - [多行的描述](#多行的描述)
+ - [用户自定义的具有数组类型的结构](#用户自定义的具有数组类型的结构)
+ - [响应对象中的模型组合](#响应对象中的模型组合)
+ - [在响应中增加头字段](#在响应中增加头字段)
+ - [使用多路径参数](#使用多路径参数)
+ - [结构体的示例值](#结构体的示例值)
+ - [结构体描述](#结构体描述)
+ - [使用`swaggertype`标签更改字段类型](#使用`swaggertype`标签更改字段类型)
+ - [使用`swaggerignore`标签排除字段](#使用swaggerignore标签排除字段)
+ - [将扩展信息添加到结构字段](#将扩展信息添加到结构字段)
+ - [对展示的模型重命名](#对展示的模型重命名)
+ - [如何使用安全性注释](#如何使用安全性注释)
+- [项目相关](#项目相关)
+
+## 快速开始
+
+1. 将注释添加到API源代码中，请参阅声明性注释格式。
+2. 使用如下命令下载swag：
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+
+从源码开始构建的话，需要有Go环境（1.18及以上版本）。
+
+或者从github的release页面下载预编译好的二进制文件。
+
+3. 在包含`main.go`文件的项目根目录运行`swag init`。这将会解析注释并生成需要的文件（`docs`文件夹和`docs/docs.go`）。
+
+```bash
+swag init
+```
+
+确保导入了生成的`docs/docs.go`文件，这样特定的配置文件才会被初始化。如果通用API注释没有写在`main.go`中，可以使用`-g`标识符来告知swag。
+
+```bash
+swag init -g http/api.go
+```
+
+4. (可选) 使用`fmt`格式化 SWAG 注释。(请先升级到最新版本)
+
+```bash
+swag fmt
+```
+
+## swag cli
+
+```bash
+swag init -h
+NAME:
+ swag init - Create docs.go
+
+USAGE:
+ 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")
+```
+
+```bash
+swag fmt -h
+NAME:
+ swag fmt - format swag comments
+
+USAGE:
+ 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](http://github.com/swaggo/gin-swagger)
+- [echo](http://github.com/swaggo/echo-swagger)
+- [buffalo](https://github.com/swaggo/buffalo-swagger)
+- [net/http](https://github.com/swaggo/http-swagger)
+- [gorilla/mux](https://github.com/swaggo/http-swagger)
+- [go-chi/chi](https://github.com/swaggo/http-swagger)
+- [flamingo](https://github.com/i-love-flamingo/swagger)
+- [fiber](https://github.com/gofiber/swagger)
+- [atreugo](https://github.com/Nerzal/atreugo-swagger)
+- [hertz](https://github.com/hertz-contrib/swagger)
+
+## 如何与Gin集成
+
+[点击此处](https://github.com/swaggo/swag/tree/master/example/celler)查看示例源代码。
+
+1. 使用`swag init`生成Swagger2.0文档后，导入如下代码包：
+
+```go
+import "github.com/swaggo/gin-swagger" // gin-swagger middleware
+import "github.com/swaggo/files" // swagger embed files
+```
+
+2. 在`main.go`源代码中添加通用的API注释：
+
+```go
+// @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")
+}
+//...
+```
+
+此外，可以动态设置一些通用的API信息。生成的代码包`docs`导出`SwaggerInfo`变量，使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例：
+
+```go
+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()
+}
+```
+
+3. 在`controller`代码中添加API操作注释：
+
+```go
+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)
+}
+//...
+```
+
+```bash
+swag init
+```
+
+4. 运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档，如下所示：
+
+
+
+## 格式化说明
+
+可以针对Swag的注释自动格式化，就像`go fmt`。
+此处查看格式化结果 [here](https://github.com/swaggo/swag/tree/master/example/celler).
+
+示例：
+```shell
+swag fmt
+```
+
+排除目录（不扫描）示例：
+```shell
+swag fmt -d ./ --exclude ./internal
+```
+
+## 开发现状
+
+[Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
+
+- [x] Basic Structure
+- [x] API Host and Base Path
+- [x] Paths and Operations
+- [x] Describing Parameters
+- [x] Describing Request Body
+- [x] Describing Responses
+- [x] MIME Types
+- [x] Authentication
+ - [x] Basic Authentication
+ - [x] API Keys
+- [x] Adding Examples
+- [x] File Upload
+- [x] Enums
+- [x] Grouping Operations With Tags
+- [ ] Swagger Extensions
+
+## 声明式注释格式
+
+## 通用API信息
+
+**示例** [`celler/main.go`](https://github.com/swaggo/swag/blob/master/example/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类型](#mime类型)”中所述。 | // @accept json |
+| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime类型)”中所述。 | // @produce json |
+| query.collection.format | 请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。 | // @query.collection.format multi |
+| schemes | 用空格分隔的请求的传输协议。 | // @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 | 扩展的键必须以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](https://github.com/swaggo/swag/tree/master/example/celler/controller)
+
+| 注释 | 描述 |
+|----------------------|------------------------------------------------------------------------------------------------|
+| description | 操作行为的详细说明。 |
+| description.markdown | 应用程序的简短描述。该描述将从名为`endpointname.md`的文件中读取。 |
+| id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 |
+| tags | 每个API操作的标签列表，以逗号分隔。 |
+| summary | 该操作的简短摘要。 |
+| accept | API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“[Mime类型](#mime类型)”中所述。 |
+| produce | API可以生成的MIME类型的列表。值必须如“[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]` |
+| deprecatedrouter | 与router相同，但是是deprecated的。 |
+| x-name | 扩展字段必须以`x-`开头，并且只能使用json值。 |
+| deprecated | 将当前API操作的所有路径设置为deprecated |
+
+## 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](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth |
+| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name | // @securityDefinitions.apikey ApiKeyAuth |
+| securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope | // @securitydefinitions.oauth2.application OAuth2Application |
+| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
+| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope | // @securitydefinitions.oauth2.password OAuth2Password |
+| securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) 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 |
+
+## 属性
+
+```go
+// @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)
+```
+
+也适用于结构体字段：
+
+```go
+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模式不同，此值务必符合此参数的定义[类型](#parameterType)。 |
+| 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` | 上面提到的[类型](#parameterType)的扩展格式。有关更多详细信息，请参见[数据类型格式](https://swagger.io/specification/v2/#dataTypeFormat)。 |
+| collectionFormat | `string` | 指定query数组参数的格式。 可能的值为： foo|bar.
+
+## 支持者
+
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]
+
+
+
+## 赞助商
+
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/swag#sponsor)]
+
+
+
+
+
+
+
+
+
+
+
+
+## License
+
+[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)
diff --git a/vendor/github.com/swaggo/swag/const.go b/vendor/github.com/swaggo/swag/const.go
new file mode 100644
index 0000000..8375510
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/const.go
@@ -0,0 +1,567 @@
+package swag
+
+import (
+ "go/ast"
+ "go/token"
+ "reflect"
+ "strconv"
+ "strings"
+ "unicode/utf8"
+)
+
+// ConstVariable a model to record a const variable
+type ConstVariable struct {
+ Name *ast.Ident
+ Type ast.Expr
+ Value interface{}
+ Comment *ast.CommentGroup
+ File *ast.File
+ Pkg *PackageDefinitions
+}
+
+var escapedChars = map[uint8]uint8{
+ 'n': '\n',
+ 'r': '\r',
+ 't': '\t',
+ 'v': '\v',
+ '\\': '\\',
+ '"': '"',
+}
+
+// EvaluateEscapedChar parse escaped character
+func EvaluateEscapedChar(text string) rune {
+ if len(text) == 1 {
+ return rune(text[0])
+ }
+
+ if len(text) == 2 && text[0] == '\\' {
+ return rune(escapedChars[text[1]])
+ }
+
+ if len(text) == 6 && text[0:2] == "\\u" {
+ n, err := strconv.ParseInt(text[2:], 16, 32)
+ if err == nil {
+ return rune(n)
+ }
+ }
+
+ return 0
+}
+
+// EvaluateEscapedString parse escaped characters in string
+func EvaluateEscapedString(text string) string {
+ if !strings.ContainsRune(text, '\\') {
+ return text
+ }
+ result := make([]byte, 0, len(text))
+ for i := 0; i < len(text); i++ {
+ if text[i] == '\\' {
+ i++
+ if text[i] == 'u' {
+ i++
+ char, err := strconv.ParseInt(text[i:i+4], 16, 32)
+ if err == nil {
+ result = utf8.AppendRune(result, rune(char))
+ }
+ i += 3
+ } else if c, ok := escapedChars[text[i]]; ok {
+ result = append(result, c)
+ }
+ } else {
+ result = append(result, text[i])
+ }
+ }
+ return string(result)
+}
+
+// EvaluateDataConversion evaluate the type a explicit type conversion
+func EvaluateDataConversion(x interface{}, typeName string) interface{} {
+ switch value := x.(type) {
+ case int:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case uint:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case int8:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case uint8:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case int16:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case uint16:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case int32:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ case "string":
+ return string(value)
+ }
+ case uint32:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case int64:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case uint64:
+ switch typeName {
+ case "int":
+ return int(value)
+ case "byte":
+ return byte(value)
+ case "int8":
+ return int8(value)
+ case "int16":
+ return int16(value)
+ case "int32":
+ return int32(value)
+ case "int64":
+ return int64(value)
+ case "uint":
+ return uint(value)
+ case "uint8":
+ return uint8(value)
+ case "uint16":
+ return uint16(value)
+ case "uint32":
+ return uint32(value)
+ case "uint64":
+ return uint64(value)
+ case "rune":
+ return rune(value)
+ }
+ case string:
+ switch typeName {
+ case "string":
+ return value
+ }
+ }
+ return nil
+}
+
+// EvaluateUnary evaluate the type and value of a unary expression
+func EvaluateUnary(x interface{}, operator token.Token, xtype ast.Expr) (interface{}, ast.Expr) {
+ switch operator {
+ case token.SUB:
+ switch value := x.(type) {
+ case int:
+ return -value, xtype
+ case int8:
+ return -value, xtype
+ case int16:
+ return -value, xtype
+ case int32:
+ return -value, xtype
+ case int64:
+ return -value, xtype
+ }
+ case token.XOR:
+ switch value := x.(type) {
+ case int:
+ return ^value, xtype
+ case int8:
+ return ^value, xtype
+ case int16:
+ return ^value, xtype
+ case int32:
+ return ^value, xtype
+ case int64:
+ return ^value, xtype
+ case uint:
+ return ^value, xtype
+ case uint8:
+ return ^value, xtype
+ case uint16:
+ return ^value, xtype
+ case uint32:
+ return ^value, xtype
+ case uint64:
+ return ^value, xtype
+ }
+ }
+ return nil, nil
+}
+
+// EvaluateBinary evaluate the type and value of a binary expression
+func EvaluateBinary(x, y interface{}, operator token.Token, xtype, ytype ast.Expr) (interface{}, ast.Expr) {
+ if operator == token.SHR || operator == token.SHL {
+ var rightOperand uint64
+ yValue := reflect.ValueOf(y)
+ if yValue.CanUint() {
+ rightOperand = yValue.Uint()
+ } else if yValue.CanInt() {
+ rightOperand = uint64(yValue.Int())
+ }
+
+ switch operator {
+ case token.SHL:
+ switch xValue := x.(type) {
+ case int:
+ return xValue << rightOperand, xtype
+ case int8:
+ return xValue << rightOperand, xtype
+ case int16:
+ return xValue << rightOperand, xtype
+ case int32:
+ return xValue << rightOperand, xtype
+ case int64:
+ return xValue << rightOperand, xtype
+ case uint:
+ return xValue << rightOperand, xtype
+ case uint8:
+ return xValue << rightOperand, xtype
+ case uint16:
+ return xValue << rightOperand, xtype
+ case uint32:
+ return xValue << rightOperand, xtype
+ case uint64:
+ return xValue << rightOperand, xtype
+ }
+ case token.SHR:
+ switch xValue := x.(type) {
+ case int:
+ return xValue >> rightOperand, xtype
+ case int8:
+ return xValue >> rightOperand, xtype
+ case int16:
+ return xValue >> rightOperand, xtype
+ case int32:
+ return xValue >> rightOperand, xtype
+ case int64:
+ return xValue >> rightOperand, xtype
+ case uint:
+ return xValue >> rightOperand, xtype
+ case uint8:
+ return xValue >> rightOperand, xtype
+ case uint16:
+ return xValue >> rightOperand, xtype
+ case uint32:
+ return xValue >> rightOperand, xtype
+ case uint64:
+ return xValue >> rightOperand, xtype
+ }
+ }
+ return nil, nil
+ }
+
+ evalType := xtype
+ if evalType == nil {
+ evalType = ytype
+ }
+
+ xValue := reflect.ValueOf(x)
+ yValue := reflect.ValueOf(y)
+ if xValue.Kind() == reflect.String && yValue.Kind() == reflect.String {
+ return xValue.String() + yValue.String(), evalType
+ }
+
+ var targetValue reflect.Value
+ if xValue.Kind() != reflect.Int {
+ targetValue = reflect.New(xValue.Type()).Elem()
+ } else {
+ targetValue = reflect.New(yValue.Type()).Elem()
+ }
+
+ switch operator {
+ case token.ADD:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() + yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() + yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) + yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() + uint64(yValue.Int()))
+ }
+ case token.SUB:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() - yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() - yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) - yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() - uint64(yValue.Int()))
+ }
+ case token.MUL:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() * yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() * yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) * yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() * uint64(yValue.Int()))
+ }
+ case token.QUO:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() / yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() / yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) / yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() / uint64(yValue.Int()))
+ }
+ case token.REM:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() % yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() % yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) % yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() % uint64(yValue.Int()))
+ }
+ case token.AND:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() & yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() & yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) & yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() & uint64(yValue.Int()))
+ }
+ case token.OR:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() | yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() | yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) | yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() | uint64(yValue.Int()))
+ }
+ case token.XOR:
+ if xValue.CanInt() && yValue.CanInt() {
+ targetValue.SetInt(xValue.Int() ^ yValue.Int())
+ } else if xValue.CanUint() && yValue.CanUint() {
+ targetValue.SetUint(xValue.Uint() ^ yValue.Uint())
+ } else if xValue.CanInt() && yValue.CanUint() {
+ targetValue.SetUint(uint64(xValue.Int()) ^ yValue.Uint())
+ } else if xValue.CanUint() && yValue.CanInt() {
+ targetValue.SetUint(xValue.Uint() ^ uint64(yValue.Int()))
+ }
+ }
+ return targetValue.Interface(), evalType
+}
diff --git a/vendor/github.com/swaggo/swag/doc.go b/vendor/github.com/swaggo/swag/doc.go
new file mode 100644
index 0000000..564b5c6
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/doc.go
@@ -0,0 +1,5 @@
+/*
+Package swag converts Go annotations to Swagger Documentation 2.0.
+See https://github.com/swaggo/swag for more information about swag.
+*/
+package swag // import "github.com/swaggo/swag"
diff --git a/vendor/github.com/swaggo/swag/enums.go b/vendor/github.com/swaggo/swag/enums.go
new file mode 100644
index 0000000..38658f2
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/enums.go
@@ -0,0 +1,13 @@
+package swag
+
+const (
+ enumVarNamesExtension = "x-enum-varnames"
+ enumCommentsExtension = "x-enum-comments"
+)
+
+// EnumValue a model to record an enum consts variable
+type EnumValue struct {
+ key string
+ Value interface{}
+ Comment string
+}
diff --git a/vendor/github.com/swaggo/swag/field_parser.go b/vendor/github.com/swaggo/swag/field_parser.go
new file mode 100644
index 0000000..9b24e78
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/field_parser.go
@@ -0,0 +1,680 @@
+package swag
+
+import (
+ "fmt"
+ "go/ast"
+ "reflect"
+ "regexp"
+ "strconv"
+ "strings"
+ "sync"
+ "unicode"
+
+ "github.com/go-openapi/spec"
+)
+
+var _ FieldParser = &tagBaseFieldParser{p: nil, field: nil, tag: ""}
+
+const (
+ requiredLabel = "required"
+ optionalLabel = "optional"
+ swaggerTypeTag = "swaggertype"
+ swaggerIgnoreTag = "swaggerignore"
+)
+
+type tagBaseFieldParser struct {
+ p *Parser
+ field *ast.Field
+ tag reflect.StructTag
+}
+
+func newTagBaseFieldParser(p *Parser, field *ast.Field) FieldParser {
+ fieldParser := tagBaseFieldParser{
+ p: p,
+ field: field,
+ tag: "",
+ }
+ if fieldParser.field.Tag != nil {
+ fieldParser.tag = reflect.StructTag(strings.ReplaceAll(field.Tag.Value, "`", ""))
+ }
+
+ return &fieldParser
+}
+
+func (ps *tagBaseFieldParser) ShouldSkip() bool {
+ // Skip non-exported fields.
+ if ps.field.Names != nil && !ast.IsExported(ps.field.Names[0].Name) {
+ return true
+ }
+
+ if ps.field.Tag == nil {
+ return false
+ }
+
+ ignoreTag := ps.tag.Get(swaggerIgnoreTag)
+ if strings.EqualFold(ignoreTag, "true") {
+ return true
+ }
+
+ // json:"tag,hoge"
+ name := strings.TrimSpace(strings.Split(ps.tag.Get(jsonTag), ",")[0])
+ if name == "-" {
+ return true
+ }
+
+ return false
+}
+
+func (ps *tagBaseFieldParser) FieldName() (string, error) {
+ var name string
+
+ if ps.field.Tag != nil {
+ // json:"tag,hoge"
+ name = strings.TrimSpace(strings.Split(ps.tag.Get(jsonTag), ",")[0])
+ if name != "" {
+ return name, nil
+ }
+
+ // use "form" tag over json tag
+ name = ps.FormName()
+ if name != "" {
+ return name, nil
+ }
+ }
+
+ if ps.field.Names == nil {
+ return "", nil
+ }
+
+ switch ps.p.PropNamingStrategy {
+ case SnakeCase:
+ return toSnakeCase(ps.field.Names[0].Name), nil
+ case PascalCase:
+ return ps.field.Names[0].Name, nil
+ default:
+ return toLowerCamelCase(ps.field.Names[0].Name), nil
+ }
+}
+
+func (ps *tagBaseFieldParser) firstTagValue(tag string) string {
+ if ps.field.Tag != nil {
+ return strings.TrimRight(strings.TrimSpace(strings.Split(ps.tag.Get(tag), ",")[0]), "[]")
+ }
+ return ""
+}
+
+func (ps *tagBaseFieldParser) FormName() string {
+ return ps.firstTagValue(formTag)
+}
+
+func (ps *tagBaseFieldParser) HeaderName() string {
+ return ps.firstTagValue(headerTag)
+}
+
+func (ps *tagBaseFieldParser) PathName() string {
+ return ps.firstTagValue(uriTag)
+}
+
+func toSnakeCase(in string) string {
+ var (
+ runes = []rune(in)
+ length = len(runes)
+ out []rune
+ )
+
+ for idx := 0; idx < length; idx++ {
+ if idx > 0 && unicode.IsUpper(runes[idx]) &&
+ ((idx+1 < length && unicode.IsLower(runes[idx+1])) || unicode.IsLower(runes[idx-1])) {
+ out = append(out, '_')
+ }
+
+ out = append(out, unicode.ToLower(runes[idx]))
+ }
+
+ return string(out)
+}
+
+func toLowerCamelCase(in string) string {
+ var flag bool
+
+ out := make([]rune, len(in))
+
+ runes := []rune(in)
+ for i, curr := range runes {
+ if (i == 0 && unicode.IsUpper(curr)) || (flag && unicode.IsUpper(curr)) {
+ out[i] = unicode.ToLower(curr)
+ flag = true
+
+ continue
+ }
+
+ out[i] = curr
+ flag = false
+ }
+
+ return string(out)
+}
+
+func (ps *tagBaseFieldParser) CustomSchema() (*spec.Schema, error) {
+ if ps.field.Tag == nil {
+ return nil, nil
+ }
+
+ typeTag := ps.tag.Get(swaggerTypeTag)
+ if typeTag != "" {
+ return BuildCustomSchema(strings.Split(typeTag, ","))
+ }
+
+ return nil, nil
+}
+
+type structField struct {
+ schemaType string
+ arrayType string
+ formatType string
+ maximum *float64
+ minimum *float64
+ multipleOf *float64
+ maxLength *int64
+ minLength *int64
+ maxItems *int64
+ minItems *int64
+ exampleValue interface{}
+ enums []interface{}
+ enumVarNames []interface{}
+ unique bool
+}
+
+// splitNotWrapped slices s into all substrings separated by sep if sep is not
+// wrapped by brackets and returns a slice of the substrings between those separators.
+func splitNotWrapped(s string, sep rune) []string {
+ openCloseMap := map[rune]rune{
+ '(': ')',
+ '[': ']',
+ '{': '}',
+ }
+
+ var (
+ result = make([]string, 0)
+ current = strings.Builder{}
+ openCount = 0
+ openChar rune
+ )
+
+ for _, char := range s {
+ switch {
+ case openChar == 0 && openCloseMap[char] != 0:
+ openChar = char
+
+ openCount++
+
+ current.WriteRune(char)
+ case char == openChar:
+ openCount++
+
+ current.WriteRune(char)
+ case openCount > 0 && char == openCloseMap[openChar]:
+ openCount--
+
+ current.WriteRune(char)
+ case openCount == 0 && char == sep:
+ result = append(result, current.String())
+
+ openChar = 0
+
+ current = strings.Builder{}
+ default:
+ current.WriteRune(char)
+ }
+ }
+
+ if current.String() != "" {
+ result = append(result, current.String())
+ }
+
+ return result
+}
+
+// ComplementSchema complement schema with field properties
+func (ps *tagBaseFieldParser) ComplementSchema(schema *spec.Schema) error {
+ types := ps.p.GetSchemaTypePath(schema, 2)
+ if len(types) == 0 {
+ return fmt.Errorf("invalid type for field: %s", ps.field.Names[0])
+ }
+
+ if IsRefSchema(schema) {
+ var newSchema = spec.Schema{}
+ err := ps.complementSchema(&newSchema, types)
+ if err != nil {
+ return err
+ }
+ if !reflect.ValueOf(newSchema).IsZero() {
+ *schema = *(newSchema.WithAllOf(*schema))
+ }
+ return nil
+ }
+
+ return ps.complementSchema(schema, types)
+}
+
+// complementSchema complement schema with field properties
+func (ps *tagBaseFieldParser) complementSchema(schema *spec.Schema, types []string) error {
+ if ps.field.Tag == nil {
+ if ps.field.Doc != nil {
+ schema.Description = strings.TrimSpace(ps.field.Doc.Text())
+ }
+
+ if schema.Description == "" && ps.field.Comment != nil {
+ schema.Description = strings.TrimSpace(ps.field.Comment.Text())
+ }
+
+ return nil
+ }
+
+ field := &structField{
+ schemaType: types[0],
+ formatType: ps.tag.Get(formatTag),
+ }
+
+ if len(types) > 1 && (types[0] == ARRAY || types[0] == OBJECT) {
+ field.arrayType = types[1]
+ }
+
+ jsonTagValue := ps.tag.Get(jsonTag)
+
+ bindingTagValue := ps.tag.Get(bindingTag)
+ if bindingTagValue != "" {
+ parseValidTags(bindingTagValue, field)
+ }
+
+ validateTagValue := ps.tag.Get(validateTag)
+ if validateTagValue != "" {
+ parseValidTags(validateTagValue, field)
+ }
+
+ enumsTagValue := ps.tag.Get(enumsTag)
+ if enumsTagValue != "" {
+ err := parseEnumTags(enumsTagValue, field)
+ if err != nil {
+ return err
+ }
+ }
+
+ if IsNumericType(field.schemaType) || IsNumericType(field.arrayType) {
+ maximum, err := getFloatTag(ps.tag, maximumTag)
+ if err != nil {
+ return err
+ }
+
+ if maximum != nil {
+ field.maximum = maximum
+ }
+
+ minimum, err := getFloatTag(ps.tag, minimumTag)
+ if err != nil {
+ return err
+ }
+
+ if minimum != nil {
+ field.minimum = minimum
+ }
+
+ multipleOf, err := getFloatTag(ps.tag, multipleOfTag)
+ if err != nil {
+ return err
+ }
+
+ if multipleOf != nil {
+ field.multipleOf = multipleOf
+ }
+ }
+
+ if field.schemaType == STRING || field.arrayType == STRING {
+ maxLength, err := getIntTag(ps.tag, maxLengthTag)
+ if err != nil {
+ return err
+ }
+
+ if maxLength != nil {
+ field.maxLength = maxLength
+ }
+
+ minLength, err := getIntTag(ps.tag, minLengthTag)
+ if err != nil {
+ return err
+ }
+
+ if minLength != nil {
+ field.minLength = minLength
+ }
+ }
+
+ // json:"name,string" or json:",string"
+ exampleTagValue, ok := ps.tag.Lookup(exampleTag)
+ if ok {
+ field.exampleValue = exampleTagValue
+
+ if !strings.Contains(jsonTagValue, ",string") {
+ example, err := defineTypeOfExample(field.schemaType, field.arrayType, exampleTagValue)
+ if err != nil {
+ return err
+ }
+
+ field.exampleValue = example
+ }
+ }
+
+ // perform this after setting everything else (min, max, etc...)
+ if strings.Contains(jsonTagValue, ",string") {
+ // @encoding/json: "It applies only to fields of string, floating point, integer, or boolean types."
+ defaultValues := map[string]string{
+ // Zero Values as string
+ STRING: "",
+ INTEGER: "0",
+ BOOLEAN: "false",
+ NUMBER: "0",
+ }
+
+ defaultValue, ok := defaultValues[field.schemaType]
+ if ok {
+ field.schemaType = STRING
+ *schema = *PrimitiveSchema(field.schemaType)
+
+ if field.exampleValue == nil {
+ // if exampleValue is not defined by the user,
+ // we will force an example with a correct value
+ // (eg: int->"0", bool:"false")
+ field.exampleValue = defaultValue
+ }
+ }
+ }
+
+ if ps.field.Doc != nil {
+ schema.Description = strings.TrimSpace(ps.field.Doc.Text())
+ }
+
+ if schema.Description == "" && ps.field.Comment != nil {
+ schema.Description = strings.TrimSpace(ps.field.Comment.Text())
+ }
+
+ schema.ReadOnly = ps.tag.Get(readOnlyTag) == "true"
+
+ defaultTagValue := ps.tag.Get(defaultTag)
+ if defaultTagValue != "" {
+ value, err := defineType(field.schemaType, defaultTagValue)
+ if err != nil {
+ return err
+ }
+
+ schema.Default = value
+ }
+
+ schema.Example = field.exampleValue
+
+ if field.schemaType != ARRAY {
+ schema.Format = field.formatType
+ }
+
+ extensionsTagValue := ps.tag.Get(extensionsTag)
+ if extensionsTagValue != "" {
+ schema.Extensions = setExtensionParam(extensionsTagValue)
+ }
+
+ varNamesTag := ps.tag.Get("x-enum-varnames")
+ if varNamesTag != "" {
+ varNames := strings.Split(varNamesTag, ",")
+ if len(varNames) != len(field.enums) {
+ return fmt.Errorf("invalid count of x-enum-varnames. expected %d, got %d", len(field.enums), len(varNames))
+ }
+
+ field.enumVarNames = nil
+
+ for _, v := range varNames {
+ field.enumVarNames = append(field.enumVarNames, v)
+ }
+
+ if field.schemaType == ARRAY {
+ // Add the var names in the items schema
+ if schema.Items.Schema.Extensions == nil {
+ schema.Items.Schema.Extensions = map[string]interface{}{}
+ }
+ schema.Items.Schema.Extensions[enumVarNamesExtension] = field.enumVarNames
+ } else {
+ // Add to top level schema
+ if schema.Extensions == nil {
+ schema.Extensions = map[string]interface{}{}
+ }
+ schema.Extensions[enumVarNamesExtension] = field.enumVarNames
+ }
+ }
+
+ eleSchema := schema
+
+ if field.schemaType == ARRAY {
+ // For Array only
+ schema.MaxItems = field.maxItems
+ schema.MinItems = field.minItems
+ schema.UniqueItems = field.unique
+
+ eleSchema = schema.Items.Schema
+ eleSchema.Format = field.formatType
+ }
+
+ eleSchema.Maximum = field.maximum
+ eleSchema.Minimum = field.minimum
+ eleSchema.MultipleOf = field.multipleOf
+ eleSchema.MaxLength = field.maxLength
+ eleSchema.MinLength = field.minLength
+ eleSchema.Enum = field.enums
+
+ return nil
+}
+
+func getFloatTag(structTag reflect.StructTag, tagName string) (*float64, error) {
+ strValue := structTag.Get(tagName)
+ if strValue == "" {
+ return nil, nil
+ }
+
+ value, err := strconv.ParseFloat(strValue, 64)
+ if err != nil {
+ return nil, fmt.Errorf("can't parse numeric value of %q tag: %v", tagName, err)
+ }
+
+ return &value, nil
+}
+
+func getIntTag(structTag reflect.StructTag, tagName string) (*int64, error) {
+ strValue := structTag.Get(tagName)
+ if strValue == "" {
+ return nil, nil
+ }
+
+ value, err := strconv.ParseInt(strValue, 10, 64)
+ if err != nil {
+ return nil, fmt.Errorf("can't parse numeric value of %q tag: %v", tagName, err)
+ }
+
+ return &value, nil
+}
+
+func (ps *tagBaseFieldParser) IsRequired() (bool, error) {
+ if ps.field.Tag == nil {
+ return false, nil
+ }
+
+ bindingTag := ps.tag.Get(bindingTag)
+ if bindingTag != "" {
+ for _, val := range strings.Split(bindingTag, ",") {
+ switch val {
+ case requiredLabel:
+ return true, nil
+ case optionalLabel:
+ return false, nil
+ }
+ }
+ }
+
+ validateTag := ps.tag.Get(validateTag)
+ if validateTag != "" {
+ for _, val := range strings.Split(validateTag, ",") {
+ switch val {
+ case requiredLabel:
+ return true, nil
+ case optionalLabel:
+ return false, nil
+ }
+ }
+ }
+
+ return ps.p.RequiredByDefault, nil
+}
+
+func parseValidTags(validTag string, sf *structField) {
+ // `validate:"required,max=10,min=1"`
+ // ps. required checked by IsRequired().
+ for _, val := range strings.Split(validTag, ",") {
+ var (
+ valValue string
+ keyVal = strings.Split(val, "=")
+ )
+
+ switch len(keyVal) {
+ case 1:
+ case 2:
+ valValue = strings.ReplaceAll(strings.ReplaceAll(keyVal[1], utf8HexComma, ","), utf8Pipe, "|")
+ default:
+ continue
+ }
+
+ switch keyVal[0] {
+ case "max", "lte":
+ sf.setMax(valValue)
+ case "min", "gte":
+ sf.setMin(valValue)
+ case "oneof":
+ sf.setOneOf(valValue)
+ case "unique":
+ if sf.schemaType == ARRAY {
+ sf.unique = true
+ }
+ case "dive":
+ // ignore dive
+ return
+ default:
+ continue
+ }
+ }
+}
+
+func parseEnumTags(enumTag string, field *structField) error {
+ enumType := field.schemaType
+ if field.schemaType == ARRAY {
+ enumType = field.arrayType
+ }
+
+ field.enums = nil
+
+ for _, e := range strings.Split(enumTag, ",") {
+ value, err := defineType(enumType, e)
+ if err != nil {
+ return err
+ }
+
+ field.enums = append(field.enums, value)
+ }
+
+ return nil
+}
+
+func (sf *structField) setOneOf(valValue string) {
+ if len(sf.enums) != 0 {
+ return
+ }
+
+ enumType := sf.schemaType
+ if sf.schemaType == ARRAY {
+ enumType = sf.arrayType
+ }
+
+ valValues := parseOneOfParam2(valValue)
+ for i := range valValues {
+ value, err := defineType(enumType, valValues[i])
+ if err != nil {
+ continue
+ }
+
+ sf.enums = append(sf.enums, value)
+ }
+}
+
+func (sf *structField) setMin(valValue string) {
+ value, err := strconv.ParseFloat(valValue, 64)
+ if err != nil {
+ return
+ }
+
+ switch sf.schemaType {
+ case INTEGER, NUMBER:
+ sf.minimum = &value
+ case STRING:
+ intValue := int64(value)
+ sf.minLength = &intValue
+ case ARRAY:
+ intValue := int64(value)
+ sf.minItems = &intValue
+ }
+}
+
+func (sf *structField) setMax(valValue string) {
+ value, err := strconv.ParseFloat(valValue, 64)
+ if err != nil {
+ return
+ }
+
+ switch sf.schemaType {
+ case INTEGER, NUMBER:
+ sf.maximum = &value
+ case STRING:
+ intValue := int64(value)
+ sf.maxLength = &intValue
+ case ARRAY:
+ intValue := int64(value)
+ sf.maxItems = &intValue
+ }
+}
+
+const (
+ utf8HexComma = "0x2C"
+ utf8Pipe = "0x7C"
+)
+
+// These code copy from
+// https://github.com/go-playground/validator/blob/d4271985b44b735c6f76abc7a06532ee997f9476/baked_in.go#L207
+// ---.
+var oneofValsCache = map[string][]string{}
+var oneofValsCacheRWLock = sync.RWMutex{}
+var splitParamsRegex = regexp.MustCompile(`'[^']*'|\S+`)
+
+func parseOneOfParam2(param string) []string {
+ oneofValsCacheRWLock.RLock()
+ values, ok := oneofValsCache[param]
+ oneofValsCacheRWLock.RUnlock()
+
+ if !ok {
+ oneofValsCacheRWLock.Lock()
+ values = splitParamsRegex.FindAllString(param, -1)
+
+ for i := 0; i < len(values); i++ {
+ values[i] = strings.ReplaceAll(values[i], "'", "")
+ }
+
+ oneofValsCache[param] = values
+
+ oneofValsCacheRWLock.Unlock()
+ }
+
+ return values
+}
+
+// ---.
diff --git a/vendor/github.com/swaggo/swag/formatter.go b/vendor/github.com/swaggo/swag/formatter.go
new file mode 100644
index 0000000..511e3a8
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/formatter.go
@@ -0,0 +1,182 @@
+package swag
+
+import (
+ "bytes"
+ "fmt"
+ "go/ast"
+ goparser "go/parser"
+ "go/token"
+ "log"
+ "os"
+ "regexp"
+ "sort"
+ "strings"
+ "text/tabwriter"
+)
+
+// Check of @Param @Success @Failure @Response @Header
+var specialTagForSplit = map[string]bool{
+ paramAttr: true,
+ successAttr: true,
+ failureAttr: true,
+ responseAttr: true,
+ headerAttr: true,
+}
+
+var skipChar = map[byte]byte{
+ '"': '"',
+ '(': ')',
+ '{': '}',
+ '[': ']',
+}
+
+// Formatter implements a formatter for Go source files.
+type Formatter struct {
+ // debugging output goes here
+ debug Debugger
+}
+
+// NewFormatter create a new formatter instance.
+func NewFormatter() *Formatter {
+ formatter := &Formatter{
+ debug: log.New(os.Stdout, "", log.LstdFlags),
+ }
+ return formatter
+}
+
+// Format formats swag comments in contents. It uses fileName to report errors
+// that happen during parsing of contents.
+func (f *Formatter) Format(fileName string, contents []byte) ([]byte, error) {
+ fileSet := token.NewFileSet()
+ ast, err := goparser.ParseFile(fileSet, fileName, contents, goparser.ParseComments)
+ if err != nil {
+ return nil, err
+ }
+
+ // Formatting changes are described as an edit list of byte range
+ // replacements. We make these content-level edits directly rather than
+ // changing the AST nodes and writing those out (via [go/printer] or
+ // [go/format]) so that we only change the formatting of Swag attribute
+ // comments. This won't touch the formatting of any other comments, or of
+ // functions, etc.
+ maxEdits := 0
+ for _, comment := range ast.Comments {
+ maxEdits += len(comment.List)
+ }
+ edits := make(edits, 0, maxEdits)
+
+ for _, comment := range ast.Comments {
+ formatFuncDoc(fileSet, comment.List, &edits)
+ }
+
+ return edits.apply(contents), nil
+}
+
+type edit struct {
+ begin int
+ end int
+ replacement []byte
+}
+
+type edits []edit
+
+func (edits edits) apply(contents []byte) []byte {
+ // Apply the edits with the highest offset first, so that earlier edits
+ // don't affect the offsets of later edits.
+ sort.Slice(edits, func(i, j int) bool {
+ return edits[i].begin > edits[j].begin
+ })
+
+ for _, edit := range edits {
+ prefix := contents[:edit.begin]
+ suffix := contents[edit.end:]
+ contents = append(prefix, append(edit.replacement, suffix...)...)
+ }
+
+ return contents
+}
+
+// formatFuncDoc reformats the comment lines in commentList, and appends any
+// changes to the edit list.
+func formatFuncDoc(fileSet *token.FileSet, commentList []*ast.Comment, edits *edits) {
+ // Building the edit list to format a comment block is a two-step process.
+ // First, we iterate over each comment line looking for Swag attributes. In
+ // each one we find, we replace alignment whitespace with a tab character,
+ // then write the result into a tab writer.
+
+ linesToComments := make(map[int]int, len(commentList))
+
+ buffer := &bytes.Buffer{}
+ w := tabwriter.NewWriter(buffer, 1, 4, 1, '\t', 0)
+
+ for commentIndex, comment := range commentList {
+ text := comment.Text
+ if attr, body, found := swagComment(text); found {
+ formatted := "//\t" + attr
+ if body != "" {
+ formatted += "\t" + splitComment2(attr, body)
+ }
+ _, _ = fmt.Fprintln(w, formatted)
+ linesToComments[len(linesToComments)] = commentIndex
+ }
+ }
+
+ // Once we've loaded all of the comment lines to be aligned into the tab
+ // writer, flushing it causes the aligned text to be written out to the
+ // backing buffer.
+ _ = w.Flush()
+
+ // Now the second step: we iterate over the aligned comment lines that were
+ // written into the backing buffer, pair each one up to its original
+ // comment line, and use the combination to describe the edit that needs to
+ // be made to the original input.
+ formattedComments := bytes.Split(buffer.Bytes(), []byte("\n"))
+ for lineIndex, commentIndex := range linesToComments {
+ comment := commentList[commentIndex]
+ *edits = append(*edits, edit{
+ begin: fileSet.Position(comment.Pos()).Offset,
+ end: fileSet.Position(comment.End()).Offset,
+ replacement: formattedComments[lineIndex],
+ })
+ }
+}
+
+func splitComment2(attr, body string) string {
+ if specialTagForSplit[strings.ToLower(attr)] {
+ for i := 0; i < len(body); i++ {
+ if skipEnd, ok := skipChar[body[i]]; ok {
+ skipStart, n := body[i], 1
+ for i++; i < len(body); i++ {
+ if skipStart != skipEnd && body[i] == skipStart {
+ n++
+ } else if body[i] == skipEnd {
+ n--
+ if n == 0 {
+ break
+ }
+ }
+ }
+ } else if body[i] == ' ' || body[i] == '\t' {
+ j := i
+ for ; j < len(body) && (body[j] == ' ' || body[j] == '\t'); j++ {
+ }
+ body = replaceRange(body, i, j, "\t")
+ }
+ }
+ }
+ return body
+}
+
+func replaceRange(s string, start, end int, new string) string {
+ return s[:start] + new + s[end:]
+}
+
+var swagCommentLineExpression = regexp.MustCompile(`^\/\/\s+(@[\S.]+)\s*(.*)`)
+
+func swagComment(comment string) (string, string, bool) {
+ matches := swagCommentLineExpression.FindStringSubmatch(comment)
+ if matches == nil {
+ return "", "", false
+ }
+ return matches[1], matches[2], true
+}
diff --git a/vendor/github.com/swaggo/swag/generics.go b/vendor/github.com/swaggo/swag/generics.go
new file mode 100644
index 0000000..07344bb
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/generics.go
@@ -0,0 +1,432 @@
+//go:build go1.18
+// +build go1.18
+
+package swag
+
+import (
+ "errors"
+ "fmt"
+ "go/ast"
+ "strings"
+ "unicode"
+
+ "github.com/go-openapi/spec"
+)
+
+type genericTypeSpec struct {
+ TypeSpec *TypeSpecDef
+ Name string
+}
+
+type formalParamType struct {
+ Name string
+ Type string
+}
+
+func (t *genericTypeSpec) TypeName() string {
+ if t.TypeSpec != nil {
+ return t.TypeSpec.TypeName()
+ }
+ return t.Name
+}
+
+func normalizeGenericTypeName(name string) string {
+ return strings.Replace(name, ".", "_", -1)
+}
+
+func (pkgDefs *PackagesDefinitions) getTypeFromGenericParam(genericParam string, file *ast.File) (typeSpecDef *TypeSpecDef) {
+ if strings.HasPrefix(genericParam, "[]") {
+ typeSpecDef = pkgDefs.getTypeFromGenericParam(genericParam[2:], file)
+ if typeSpecDef == nil {
+ return nil
+ }
+ var expr ast.Expr
+ switch typeSpecDef.TypeSpec.Type.(type) {
+ case *ast.ArrayType, *ast.MapType:
+ expr = typeSpecDef.TypeSpec.Type
+ default:
+ name := typeSpecDef.TypeName()
+ expr = ast.NewIdent(name)
+ if _, ok := pkgDefs.uniqueDefinitions[name]; !ok {
+ pkgDefs.uniqueDefinitions[name] = typeSpecDef
+ }
+ }
+ return &TypeSpecDef{
+ TypeSpec: &ast.TypeSpec{
+ Name: ast.NewIdent(string(IgnoreNameOverridePrefix) + "array_" + typeSpecDef.TypeName()),
+ Type: &ast.ArrayType{
+ Elt: expr,
+ },
+ },
+ Enums: typeSpecDef.Enums,
+ PkgPath: typeSpecDef.PkgPath,
+ ParentSpec: typeSpecDef.ParentSpec,
+ NotUnique: false,
+ }
+ }
+
+ if strings.HasPrefix(genericParam, "map[") {
+ parts := strings.SplitN(genericParam[4:], "]", 2)
+ if len(parts) != 2 {
+ return nil
+ }
+ typeSpecDef = pkgDefs.getTypeFromGenericParam(parts[1], file)
+ if typeSpecDef == nil {
+ return nil
+ }
+ var expr ast.Expr
+ switch typeSpecDef.TypeSpec.Type.(type) {
+ case *ast.ArrayType, *ast.MapType:
+ expr = typeSpecDef.TypeSpec.Type
+ default:
+ name := typeSpecDef.TypeName()
+ expr = ast.NewIdent(name)
+ if _, ok := pkgDefs.uniqueDefinitions[name]; !ok {
+ pkgDefs.uniqueDefinitions[name] = typeSpecDef
+ }
+ }
+ return &TypeSpecDef{
+ TypeSpec: &ast.TypeSpec{
+ Name: ast.NewIdent(string(IgnoreNameOverridePrefix) + "map_" + parts[0] + "_" + typeSpecDef.TypeName()),
+ Type: &ast.MapType{
+ Key: ast.NewIdent(parts[0]), //assume key is string or integer
+ Value: expr,
+ },
+ },
+ Enums: typeSpecDef.Enums,
+ PkgPath: typeSpecDef.PkgPath,
+ ParentSpec: typeSpecDef.ParentSpec,
+ NotUnique: false,
+ }
+
+ }
+ if IsGolangPrimitiveType(genericParam) {
+ return &TypeSpecDef{
+ TypeSpec: &ast.TypeSpec{
+ Name: ast.NewIdent(genericParam),
+ Type: ast.NewIdent(genericParam),
+ },
+ }
+ }
+ return pkgDefs.FindTypeSpec(genericParam, file)
+}
+
+func (pkgDefs *PackagesDefinitions) parametrizeGenericType(file *ast.File, original *TypeSpecDef, fullGenericForm string) *TypeSpecDef {
+ if original == nil || original.TypeSpec.TypeParams == nil || len(original.TypeSpec.TypeParams.List) == 0 {
+ return original
+ }
+
+ name, genericParams := splitGenericsTypeName(fullGenericForm)
+ if genericParams == nil {
+ return nil
+ }
+
+ //generic[x,y any,z any] considered, TODO what if the type is not `any`, but a concrete one, such as `int32|int64` or an certain interface{}
+ var formals []formalParamType
+ for _, field := range original.TypeSpec.TypeParams.List {
+ for _, ident := range field.Names {
+ formal := formalParamType{Name: ident.Name}
+ if ident, ok := field.Type.(*ast.Ident); ok {
+ formal.Type = ident.Name
+ }
+ formals = append(formals, formal)
+ }
+ }
+ if len(genericParams) != len(formals) {
+ return nil
+ }
+ genericParamTypeDefs := map[string]*genericTypeSpec{}
+
+ for i, genericParam := range genericParams {
+ var typeDef *TypeSpecDef
+ if !IsGolangPrimitiveType(genericParam) {
+ typeDef = pkgDefs.getTypeFromGenericParam(genericParam, file)
+ if typeDef != nil {
+ genericParam = typeDef.TypeName()
+ if _, ok := pkgDefs.uniqueDefinitions[genericParam]; !ok {
+ pkgDefs.uniqueDefinitions[genericParam] = typeDef
+ }
+ }
+ }
+ genericParamTypeDefs[formals[i].Name] = &genericTypeSpec{
+ TypeSpec: typeDef,
+ Name: genericParam,
+ }
+ }
+
+ name = fmt.Sprintf("%s%s-", string(IgnoreNameOverridePrefix), original.TypeName())
+ var nameParts []string
+ for _, def := range formals {
+ if specDef, ok := genericParamTypeDefs[def.Name]; ok {
+ nameParts = append(nameParts, specDef.TypeName())
+ }
+ }
+
+ name += normalizeGenericTypeName(strings.Join(nameParts, "-"))
+
+ if typeSpec, ok := pkgDefs.uniqueDefinitions[name]; ok {
+ return typeSpec
+ }
+
+ parametrizedTypeSpec := &TypeSpecDef{
+ File: original.File,
+ PkgPath: original.PkgPath,
+ TypeSpec: &ast.TypeSpec{
+ Name: &ast.Ident{
+ Name: name,
+ NamePos: original.TypeSpec.Name.NamePos,
+ Obj: original.TypeSpec.Name.Obj,
+ },
+ Doc: original.TypeSpec.Doc,
+ Assign: original.TypeSpec.Assign,
+ },
+ }
+ pkgDefs.uniqueDefinitions[name] = parametrizedTypeSpec
+
+ parametrizedTypeSpec.TypeSpec.Type = pkgDefs.resolveGenericType(original.File, original.TypeSpec.Type, genericParamTypeDefs)
+
+ return parametrizedTypeSpec
+}
+
+// splitGenericsTypeName splits a generic struct name in his parts
+func splitGenericsTypeName(fullGenericForm string) (string, []string) {
+ //remove all spaces character
+ fullGenericForm = strings.Map(func(r rune) rune {
+ if unicode.IsSpace(r) {
+ return -1
+ }
+ return r
+ }, fullGenericForm)
+
+ // split only at the first '[' and remove the last ']'
+ if fullGenericForm[len(fullGenericForm)-1] != ']' {
+ return "", nil
+ }
+
+ genericParams := strings.SplitN(fullGenericForm[:len(fullGenericForm)-1], "[", 2)
+ if len(genericParams) == 1 {
+ return "", nil
+ }
+
+ // generic type name
+ genericTypeName := genericParams[0]
+
+ depth := 0
+ genericParams = strings.FieldsFunc(genericParams[1], func(r rune) bool {
+ if r == '[' {
+ depth++
+ } else if r == ']' {
+ depth--
+ } else if r == ',' && depth == 0 {
+ return true
+ }
+ return false
+ })
+ if depth != 0 {
+ return "", nil
+ }
+
+ return genericTypeName, genericParams
+}
+
+func (pkgDefs *PackagesDefinitions) getParametrizedType(genTypeSpec *genericTypeSpec) ast.Expr {
+ if genTypeSpec.TypeSpec != nil && strings.Contains(genTypeSpec.Name, ".") {
+ parts := strings.SplitN(genTypeSpec.Name, ".", 2)
+ return &ast.SelectorExpr{
+ X: &ast.Ident{Name: parts[0]},
+ Sel: &ast.Ident{Name: parts[1]},
+ }
+ }
+
+ //a primitive type name or a type name in current package
+ return &ast.Ident{Name: genTypeSpec.Name}
+}
+
+func (pkgDefs *PackagesDefinitions) resolveGenericType(file *ast.File, expr ast.Expr, genericParamTypeDefs map[string]*genericTypeSpec) ast.Expr {
+ switch astExpr := expr.(type) {
+ case *ast.Ident:
+ if genTypeSpec, ok := genericParamTypeDefs[astExpr.Name]; ok {
+ return pkgDefs.getParametrizedType(genTypeSpec)
+ }
+ case *ast.ArrayType:
+ return &ast.ArrayType{
+ Elt: pkgDefs.resolveGenericType(file, astExpr.Elt, genericParamTypeDefs),
+ Len: astExpr.Len,
+ Lbrack: astExpr.Lbrack,
+ }
+ case *ast.MapType:
+ return &ast.MapType{
+ Map: astExpr.Map,
+ Key: pkgDefs.resolveGenericType(file, astExpr.Key, genericParamTypeDefs),
+ Value: pkgDefs.resolveGenericType(file, astExpr.Value, genericParamTypeDefs),
+ }
+ case *ast.StarExpr:
+ return &ast.StarExpr{
+ Star: astExpr.Star,
+ X: pkgDefs.resolveGenericType(file, astExpr.X, genericParamTypeDefs),
+ }
+ case *ast.IndexExpr, *ast.IndexListExpr:
+ fullGenericName, _ := getGenericFieldType(file, expr, genericParamTypeDefs)
+ typeDef := pkgDefs.FindTypeSpec(fullGenericName, file)
+ if typeDef != nil {
+ return typeDef.TypeSpec.Name
+ }
+ case *ast.StructType:
+ newStructTypeDef := &ast.StructType{
+ Struct: astExpr.Struct,
+ Incomplete: astExpr.Incomplete,
+ Fields: &ast.FieldList{
+ Opening: astExpr.Fields.Opening,
+ Closing: astExpr.Fields.Closing,
+ },
+ }
+
+ for _, field := range astExpr.Fields.List {
+ newField := &ast.Field{
+ Type: field.Type,
+ Doc: field.Doc,
+ Names: field.Names,
+ Tag: field.Tag,
+ Comment: field.Comment,
+ }
+
+ newField.Type = pkgDefs.resolveGenericType(file, field.Type, genericParamTypeDefs)
+
+ newStructTypeDef.Fields.List = append(newStructTypeDef.Fields.List, newField)
+ }
+ return newStructTypeDef
+ }
+ return expr
+}
+
+func getExtendedGenericFieldType(file *ast.File, field ast.Expr, genericParamTypeDefs map[string]*genericTypeSpec) (string, error) {
+ switch fieldType := field.(type) {
+ case *ast.ArrayType:
+ fieldName, err := getExtendedGenericFieldType(file, fieldType.Elt, genericParamTypeDefs)
+ return "[]" + fieldName, err
+ case *ast.StarExpr:
+ return getExtendedGenericFieldType(file, fieldType.X, genericParamTypeDefs)
+ case *ast.Ident:
+ if genericParamTypeDefs != nil {
+ if typeSpec, ok := genericParamTypeDefs[fieldType.Name]; ok {
+ return typeSpec.Name, nil
+ }
+ }
+ if fieldType.Obj == nil {
+ return fieldType.Name, nil
+ }
+
+ tSpec := &TypeSpecDef{
+ File: file,
+ TypeSpec: fieldType.Obj.Decl.(*ast.TypeSpec),
+ PkgPath: file.Name.Name,
+ }
+ return tSpec.TypeName(), nil
+ default:
+ return getFieldType(file, field, genericParamTypeDefs)
+ }
+}
+
+func getGenericFieldType(file *ast.File, field ast.Expr, genericParamTypeDefs map[string]*genericTypeSpec) (string, error) {
+ var fullName string
+ var baseName string
+ var err error
+ switch fieldType := field.(type) {
+ case *ast.IndexListExpr:
+ baseName, err = getGenericTypeName(file, fieldType.X)
+ if err != nil {
+ return "", err
+ }
+ fullName = baseName + "["
+
+ for _, index := range fieldType.Indices {
+ fieldName, err := getExtendedGenericFieldType(file, index, genericParamTypeDefs)
+ if err != nil {
+ return "", err
+ }
+
+ fullName += fieldName + ","
+ }
+
+ fullName = strings.TrimRight(fullName, ",") + "]"
+ case *ast.IndexExpr:
+ baseName, err = getGenericTypeName(file, fieldType.X)
+ if err != nil {
+ return "", err
+ }
+
+ indexName, err := getExtendedGenericFieldType(file, fieldType.Index, genericParamTypeDefs)
+ if err != nil {
+ return "", err
+ }
+
+ fullName = fmt.Sprintf("%s[%s]", baseName, indexName)
+ }
+
+ if fullName == "" {
+ return "", fmt.Errorf("unknown field type %#v", field)
+ }
+
+ var packageName string
+ if !strings.Contains(baseName, ".") {
+ if file.Name == nil {
+ return "", errors.New("file name is nil")
+ }
+ packageName, _ = getFieldType(file, file.Name, genericParamTypeDefs)
+ }
+
+ return strings.TrimLeft(fmt.Sprintf("%s.%s", packageName, fullName), "."), nil
+}
+
+func getGenericTypeName(file *ast.File, field ast.Expr) (string, error) {
+ switch fieldType := field.(type) {
+ case *ast.Ident:
+ if fieldType.Obj == nil {
+ return fieldType.Name, nil
+ }
+
+ tSpec := &TypeSpecDef{
+ File: file,
+ TypeSpec: fieldType.Obj.Decl.(*ast.TypeSpec),
+ PkgPath: file.Name.Name,
+ }
+ return tSpec.TypeName(), nil
+ case *ast.ArrayType:
+ tSpec := &TypeSpecDef{
+ File: file,
+ TypeSpec: fieldType.Elt.(*ast.Ident).Obj.Decl.(*ast.TypeSpec),
+ PkgPath: file.Name.Name,
+ }
+ return tSpec.TypeName(), nil
+ case *ast.SelectorExpr:
+ return fmt.Sprintf("%s.%s", fieldType.X.(*ast.Ident).Name, fieldType.Sel.Name), nil
+ }
+ return "", fmt.Errorf("unknown type %#v", field)
+}
+
+func (parser *Parser) parseGenericTypeExpr(file *ast.File, typeExpr ast.Expr) (*spec.Schema, error) {
+ switch expr := typeExpr.(type) {
+ // suppress debug messages for these types
+ case *ast.InterfaceType:
+ case *ast.StructType:
+ case *ast.Ident:
+ case *ast.StarExpr:
+ case *ast.SelectorExpr:
+ case *ast.ArrayType:
+ case *ast.MapType:
+ case *ast.FuncType:
+ case *ast.IndexExpr, *ast.IndexListExpr:
+ name, err := getExtendedGenericFieldType(file, expr, nil)
+ if err == nil {
+ if schema, err := parser.getTypeSchema(name, file, false); err == nil {
+ return schema, nil
+ }
+ }
+
+ parser.debug.Printf("Type definition of type '%T' is not supported yet. Using 'object' instead. (%s)\n", typeExpr, err)
+ default:
+ parser.debug.Printf("Type definition of type '%T' is not supported yet. Using 'object' instead.\n", typeExpr)
+ }
+
+ return PrimitiveSchema(OBJECT), nil
+}
diff --git a/vendor/github.com/swaggo/swag/golist.go b/vendor/github.com/swaggo/swag/golist.go
new file mode 100644
index 0000000..fa0b2cd
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/golist.go
@@ -0,0 +1,78 @@
+package swag
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "go/build"
+ "os/exec"
+ "path/filepath"
+)
+
+func listPackages(ctx context.Context, dir string, env []string, args ...string) (pkgs []*build.Package, finalErr error) {
+ cmd := exec.CommandContext(ctx, "go", append([]string{"list", "-json", "-e"}, args...)...)
+ cmd.Env = env
+ cmd.Dir = dir
+
+ stdout, err := cmd.StdoutPipe()
+ if err != nil {
+ return nil, err
+ }
+ var stderrBuf bytes.Buffer
+ cmd.Stderr = &stderrBuf
+ defer func() {
+ if stderrBuf.Len() > 0 {
+ finalErr = fmt.Errorf("%v\n%s", finalErr, stderrBuf.Bytes())
+ }
+ }()
+
+ err = cmd.Start()
+ if err != nil {
+ return nil, err
+ }
+ dec := json.NewDecoder(stdout)
+ for dec.More() {
+ var pkg build.Package
+ err = dec.Decode(&pkg)
+ if err != nil {
+ return nil, err
+ }
+ pkgs = append(pkgs, &pkg)
+ }
+ err = cmd.Wait()
+ if err != nil {
+ return nil, err
+ }
+ return pkgs, nil
+}
+
+func (parser *Parser) getAllGoFileInfoFromDepsByList(pkg *build.Package, parseFlag ParseFlag) error {
+ ignoreInternal := pkg.Goroot && !parser.ParseInternal
+ if ignoreInternal { // ignored internal
+ return nil
+ }
+
+ if parser.skipPackageByPrefix(pkg.ImportPath) {
+ return nil // ignored by user-defined package path prefixes
+ }
+
+ srcDir := pkg.Dir
+ var err error
+ for i := range pkg.GoFiles {
+ err = parser.parseFile(pkg.ImportPath, filepath.Join(srcDir, pkg.GoFiles[i]), nil, parseFlag)
+ if err != nil {
+ return err
+ }
+ }
+
+ // parse .go source files that import "C"
+ for i := range pkg.CgoFiles {
+ err = parser.parseFile(pkg.ImportPath, filepath.Join(srcDir, pkg.CgoFiles[i]), nil, parseFlag)
+ if err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
diff --git a/vendor/github.com/swaggo/swag/license b/vendor/github.com/swaggo/swag/license
new file mode 100644
index 0000000..a97865b
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/license
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Eason Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/vendor/github.com/swaggo/swag/operation.go b/vendor/github.com/swaggo/swag/operation.go
new file mode 100644
index 0000000..169510f
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/operation.go
@@ -0,0 +1,1245 @@
+package swag
+
+import (
+ "encoding/json"
+ "fmt"
+ "go/ast"
+ goparser "go/parser"
+ "go/token"
+ "net/http"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strconv"
+ "strings"
+
+ "github.com/go-openapi/spec"
+ "golang.org/x/tools/go/loader"
+)
+
+// RouteProperties describes HTTP properties of a single router comment.
+type RouteProperties struct {
+ HTTPMethod string
+ Path string
+ Deprecated bool
+}
+
+// Operation describes a single API operation on a path.
+// For more information: https://github.com/swaggo/swag#api-operation
+type Operation struct {
+ parser *Parser
+ codeExampleFilesDir string
+ spec.Operation
+ RouterProperties []RouteProperties
+ State string
+}
+
+var mimeTypeAliases = map[string]string{
+ "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",
+}
+
+var mimeTypePattern = regexp.MustCompile("^[^/]+/[^/]+$")
+
+// NewOperation creates a new Operation with default properties.
+// map[int]Response.
+func NewOperation(parser *Parser, options ...func(*Operation)) *Operation {
+ if parser == nil {
+ parser = New()
+ }
+
+ result := &Operation{
+ parser: parser,
+ RouterProperties: []RouteProperties{},
+ Operation: spec.Operation{
+ OperationProps: spec.OperationProps{
+ ID: "",
+ Description: "",
+ Summary: "",
+ Security: nil,
+ ExternalDocs: nil,
+ Deprecated: false,
+ Tags: []string{},
+ Consumes: []string{},
+ Produces: []string{},
+ Schemes: []string{},
+ Parameters: []spec.Parameter{},
+ Responses: &spec.Responses{
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: spec.Extensions{},
+ },
+ ResponsesProps: spec.ResponsesProps{
+ Default: nil,
+ StatusCodeResponses: make(map[int]spec.Response),
+ },
+ },
+ },
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: spec.Extensions{},
+ },
+ },
+ codeExampleFilesDir: "",
+ }
+
+ for _, option := range options {
+ option(result)
+ }
+
+ return result
+}
+
+// SetCodeExampleFilesDirectory sets the directory to search for codeExamples.
+func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation) {
+ return func(o *Operation) {
+ o.codeExampleFilesDir = directoryPath
+ }
+}
+
+// ParseComment parses comment for given comment string and returns error if error occurs.
+func (operation *Operation) ParseComment(comment string, astFile *ast.File) error {
+ commentLine := strings.TrimSpace(strings.TrimLeft(comment, "/"))
+ if len(commentLine) == 0 {
+ return nil
+ }
+
+ fields := FieldsByAnySpace(commentLine, 2)
+ attribute := fields[0]
+ lowerAttribute := strings.ToLower(attribute)
+ var lineRemainder string
+ if len(fields) > 1 {
+ lineRemainder = fields[1]
+ }
+ switch lowerAttribute {
+ case stateAttr:
+ operation.ParseStateComment(lineRemainder)
+ case descriptionAttr:
+ operation.ParseDescriptionComment(lineRemainder)
+ case descriptionMarkdownAttr:
+ commentInfo, err := getMarkdownForTag(lineRemainder, operation.parser.markdownFileDir)
+ if err != nil {
+ return err
+ }
+
+ operation.ParseDescriptionComment(string(commentInfo))
+ case summaryAttr:
+ operation.Summary = lineRemainder
+ case idAttr:
+ operation.ID = lineRemainder
+ case tagsAttr:
+ operation.ParseTagsComment(lineRemainder)
+ case acceptAttr:
+ return operation.ParseAcceptComment(lineRemainder)
+ case produceAttr:
+ return operation.ParseProduceComment(lineRemainder)
+ case paramAttr:
+ return operation.ParseParamComment(lineRemainder, astFile)
+ case successAttr, failureAttr, responseAttr:
+ return operation.ParseResponseComment(lineRemainder, astFile)
+ case headerAttr:
+ return operation.ParseResponseHeaderComment(lineRemainder, astFile)
+ case routerAttr:
+ return operation.ParseRouterComment(lineRemainder, false)
+ case deprecatedRouterAttr:
+ return operation.ParseRouterComment(lineRemainder, true)
+ case securityAttr:
+ return operation.ParseSecurityComment(lineRemainder)
+ case deprecatedAttr:
+ operation.Deprecate()
+ case xCodeSamplesAttr:
+ return operation.ParseCodeSample(attribute, commentLine, lineRemainder)
+ default:
+ return operation.ParseMetadata(attribute, lowerAttribute, lineRemainder)
+ }
+
+ return nil
+}
+
+// ParseCodeSample parse code sample.
+func (operation *Operation) ParseCodeSample(attribute, _, lineRemainder string) error {
+ if lineRemainder == "file" {
+ data, err := getCodeExampleForSummary(operation.Summary, operation.codeExampleFilesDir)
+ if err != nil {
+ return err
+ }
+
+ var valueJSON interface{}
+
+ err = json.Unmarshal(data, &valueJSON)
+ if err != nil {
+ return fmt.Errorf("annotation %s need a valid json value", attribute)
+ }
+
+ // don't use the method provided by spec lib, because it will call toLower() on attribute names, which is wrongly
+ operation.Extensions[attribute[1:]] = valueJSON
+
+ return nil
+ }
+
+ // Fallback into existing logic
+ return operation.ParseMetadata(attribute, strings.ToLower(attribute), lineRemainder)
+}
+
+// ParseStateComment parse state comment.
+func (operation *Operation) ParseStateComment(lineRemainder string) {
+ operation.State = lineRemainder
+}
+
+// ParseDescriptionComment parse description comment.
+func (operation *Operation) ParseDescriptionComment(lineRemainder string) {
+ if operation.Description == "" {
+ operation.Description = lineRemainder
+
+ return
+ }
+
+ operation.Description += "\n" + lineRemainder
+}
+
+// ParseMetadata parse metadata.
+func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error {
+ // parsing specific meta data extensions
+ if strings.HasPrefix(lowerAttribute, "@x-") {
+ if len(lineRemainder) == 0 {
+ return fmt.Errorf("annotation %s need a value", attribute)
+ }
+
+ var valueJSON interface{}
+
+ err := json.Unmarshal([]byte(lineRemainder), &valueJSON)
+ if err != nil {
+ return fmt.Errorf("annotation %s need a valid json value", attribute)
+ }
+
+ // don't use the method provided by spec lib, because it will call toLower() on attribute names, which is wrongly
+ operation.Extensions[attribute[1:]] = valueJSON
+ }
+
+ return nil
+}
+
+var paramPattern = regexp.MustCompile(`(\S+)\s+(\w+)\s+([\S. ]+?)\s+(\w+)\s+"([^"]+)"`)
+
+func findInSlice(arr []string, target string) bool {
+ for _, str := range arr {
+ if str == target {
+ return true
+ }
+ }
+
+ return false
+}
+
+// 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 *Operation) ParseParamComment(commentLine string, astFile *ast.File) error {
+ matches := paramPattern.FindStringSubmatch(commentLine)
+ if len(matches) != 6 {
+ return fmt.Errorf("missing required param comment parameters \"%s\"", commentLine)
+ }
+
+ name := matches[1]
+ paramType := matches[2]
+ refType := TransToValidSchemeType(matches[3])
+
+ // Detect refType
+ objectType := OBJECT
+
+ if strings.HasPrefix(refType, "[]") {
+ objectType = ARRAY
+ refType = strings.TrimPrefix(refType, "[]")
+ refType = TransToValidSchemeType(refType)
+ } else if IsPrimitiveType(refType) ||
+ paramType == "formData" && refType == "file" {
+ objectType = PRIMITIVE
+ }
+
+ var enums []interface{}
+ if !IsPrimitiveType(refType) {
+ schema, _ := operation.parser.getTypeSchema(refType, astFile, false)
+ if schema != nil && len(schema.Type) == 1 && schema.Enum != nil {
+ if objectType == OBJECT {
+ objectType = PRIMITIVE
+ }
+ refType = TransToValidSchemeType(schema.Type[0])
+ enums = schema.Enum
+ }
+ }
+
+ requiredText := strings.ToLower(matches[4])
+ required := requiredText == "true" || requiredText == requiredLabel
+ description := matches[5]
+
+ param := createParameter(paramType, description, name, objectType, refType, required, enums, operation.parser.collectionFormatInQuery)
+
+ switch paramType {
+ case "path", "header", "query", "formData":
+ switch objectType {
+ case ARRAY:
+ if !IsPrimitiveType(refType) && !(refType == "file" && paramType == "formData") {
+ return fmt.Errorf("%s is not supported array type for %s", refType, paramType)
+ }
+ case PRIMITIVE:
+ break
+ case OBJECT:
+ schema, err := operation.parser.getTypeSchema(refType, astFile, false)
+ if err != nil {
+ return err
+ }
+
+ if len(schema.Properties) == 0 {
+ return nil
+ }
+
+ items := schema.Properties.ToOrderedSchemaItems()
+
+ for _, item := range items {
+ name, prop := item.Name, &item.Schema
+ if len(prop.Type) == 0 {
+ prop = operation.parser.getUnderlyingSchema(prop)
+ if len(prop.Type) == 0 {
+ continue
+ }
+ }
+
+ nameOverrideType := paramType
+ // query also uses formData tags
+ if paramType == "query" {
+ nameOverrideType = "formData"
+ }
+ // load overridden type specific name from extensions if exists
+ if nameVal, ok := item.Schema.Extensions[nameOverrideType]; ok {
+ name = nameVal.(string)
+ }
+
+ switch {
+ case prop.Type[0] == ARRAY:
+ if prop.Items.Schema == nil {
+ continue
+ }
+ itemSchema := prop.Items.Schema
+ if len(itemSchema.Type) == 0 {
+ itemSchema = operation.parser.getUnderlyingSchema(prop.Items.Schema)
+ }
+ if len(itemSchema.Type) == 0 {
+ continue
+ }
+ if !IsSimplePrimitiveType(itemSchema.Type[0]) {
+ continue
+ }
+ param = createParameter(paramType, prop.Description, name, prop.Type[0], itemSchema.Type[0], findInSlice(schema.Required, item.Name), itemSchema.Enum, operation.parser.collectionFormatInQuery)
+
+ case IsSimplePrimitiveType(prop.Type[0]):
+ param = createParameter(paramType, prop.Description, name, PRIMITIVE, prop.Type[0], findInSlice(schema.Required, item.Name), nil, operation.parser.collectionFormatInQuery)
+ default:
+ operation.parser.debug.Printf("skip field [%s] in %s is not supported type for %s", name, refType, paramType)
+ continue
+ }
+
+ param.Nullable = prop.Nullable
+ param.Format = prop.Format
+ param.Default = prop.Default
+ param.Example = prop.Example
+ param.Extensions = prop.Extensions
+ param.CommonValidations.Maximum = prop.Maximum
+ param.CommonValidations.Minimum = prop.Minimum
+ param.CommonValidations.ExclusiveMaximum = prop.ExclusiveMaximum
+ param.CommonValidations.ExclusiveMinimum = prop.ExclusiveMinimum
+ param.CommonValidations.MaxLength = prop.MaxLength
+ param.CommonValidations.MinLength = prop.MinLength
+ param.CommonValidations.Pattern = prop.Pattern
+ param.CommonValidations.MaxItems = prop.MaxItems
+ param.CommonValidations.MinItems = prop.MinItems
+ param.CommonValidations.UniqueItems = prop.UniqueItems
+ param.CommonValidations.MultipleOf = prop.MultipleOf
+ param.CommonValidations.Enum = prop.Enum
+ operation.Operation.Parameters = append(operation.Operation.Parameters, param)
+ }
+
+ return nil
+ }
+ case "body":
+ if objectType == PRIMITIVE {
+ param.Schema = PrimitiveSchema(refType)
+ } else {
+ schema, err := operation.parseAPIObjectSchema(commentLine, objectType, refType, astFile)
+ if err != nil {
+ return err
+ }
+
+ param.Schema = schema
+ }
+ default:
+ return fmt.Errorf("%s is not supported paramType", paramType)
+ }
+
+ err := operation.parseParamAttribute(commentLine, objectType, refType, paramType, ¶m)
+
+ if err != nil {
+ return err
+ }
+
+ operation.Operation.Parameters = append(operation.Operation.Parameters, param)
+
+ return nil
+}
+
+const (
+ formTag = "form"
+ jsonTag = "json"
+ uriTag = "uri"
+ headerTag = "header"
+ bindingTag = "binding"
+ defaultTag = "default"
+ enumsTag = "enums"
+ exampleTag = "example"
+ schemaExampleTag = "schemaExample"
+ formatTag = "format"
+ validateTag = "validate"
+ minimumTag = "minimum"
+ maximumTag = "maximum"
+ minLengthTag = "minLength"
+ maxLengthTag = "maxLength"
+ multipleOfTag = "multipleOf"
+ readOnlyTag = "readonly"
+ extensionsTag = "extensions"
+ collectionFormatTag = "collectionFormat"
+)
+
+var regexAttributes = map[string]*regexp.Regexp{
+ // for Enums(A, B)
+ enumsTag: regexp.MustCompile(`(?i)\s+enums\(.*\)`),
+ // for maximum(0)
+ maximumTag: regexp.MustCompile(`(?i)\s+maxinum|maximum\(.*\)`),
+ // for minimum(0)
+ minimumTag: regexp.MustCompile(`(?i)\s+mininum|minimum\(.*\)`),
+ // for default(0)
+ defaultTag: regexp.MustCompile(`(?i)\s+default\(.*\)`),
+ // for minlength(0)
+ minLengthTag: regexp.MustCompile(`(?i)\s+minlength\(.*\)`),
+ // for maxlength(0)
+ maxLengthTag: regexp.MustCompile(`(?i)\s+maxlength\(.*\)`),
+ // for format(email)
+ formatTag: regexp.MustCompile(`(?i)\s+format\(.*\)`),
+ // for extensions(x-example=test)
+ extensionsTag: regexp.MustCompile(`(?i)\s+extensions\(.*\)`),
+ // for collectionFormat(csv)
+ collectionFormatTag: regexp.MustCompile(`(?i)\s+collectionFormat\(.*\)`),
+ // example(0)
+ exampleTag: regexp.MustCompile(`(?i)\s+example\(.*\)`),
+ // schemaExample(0)
+ schemaExampleTag: regexp.MustCompile(`(?i)\s+schemaExample\(.*\)`),
+}
+
+func (operation *Operation) parseParamAttribute(comment, objectType, schemaType, paramType string, param *spec.Parameter) error {
+ schemaType = TransToValidSchemeType(schemaType)
+
+ for attrKey, re := range regexAttributes {
+ attr, err := findAttr(re, comment)
+ if err != nil {
+ continue
+ }
+
+ switch attrKey {
+ case enumsTag:
+ err = setEnumParam(param, attr, objectType, schemaType, paramType)
+ case minimumTag, maximumTag:
+ err = setNumberParam(param, attrKey, schemaType, attr, comment)
+ case defaultTag:
+ err = setDefault(param, schemaType, attr)
+ case minLengthTag, maxLengthTag:
+ err = setStringParam(param, attrKey, schemaType, attr, comment)
+ case formatTag:
+ param.Format = attr
+ case exampleTag:
+ err = setExample(param, schemaType, attr)
+ case schemaExampleTag:
+ err = setSchemaExample(param, schemaType, attr)
+ case extensionsTag:
+ param.Extensions = setExtensionParam(attr)
+ case collectionFormatTag:
+ err = setCollectionFormatParam(param, attrKey, objectType, attr, comment)
+ }
+
+ if err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+func findAttr(re *regexp.Regexp, commentLine string) (string, error) {
+ attr := re.FindString(commentLine)
+
+ l, r := strings.Index(attr, "("), strings.Index(attr, ")")
+ if l == -1 || r == -1 {
+ return "", fmt.Errorf("can not find regex=%s, comment=%s", re.String(), commentLine)
+ }
+
+ return strings.TrimSpace(attr[l+1 : r]), nil
+}
+
+func setStringParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {
+ if schemaType != STRING {
+ return fmt.Errorf("%s is attribute to set to a number. comment=%s got=%s", name, commentLine, schemaType)
+ }
+
+ n, err := strconv.ParseInt(attr, 10, 64)
+ if err != nil {
+ return fmt.Errorf("%s is allow only a number got=%s", name, attr)
+ }
+
+ switch name {
+ case minLengthTag:
+ param.MinLength = &n
+ case maxLengthTag:
+ param.MaxLength = &n
+ }
+
+ return nil
+}
+
+func setNumberParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {
+ switch schemaType {
+ case INTEGER, NUMBER:
+ n, err := strconv.ParseFloat(attr, 64)
+ if err != nil {
+ return fmt.Errorf("maximum is allow only a number. comment=%s got=%s", commentLine, attr)
+ }
+
+ switch name {
+ case minimumTag:
+ param.Minimum = &n
+ case maximumTag:
+ param.Maximum = &n
+ }
+
+ return nil
+ default:
+ return fmt.Errorf("%s is attribute to set to a number. comment=%s got=%s", name, commentLine, schemaType)
+ }
+}
+
+func setEnumParam(param *spec.Parameter, attr, objectType, schemaType, paramType string) error {
+ for _, e := range strings.Split(attr, ",") {
+ e = strings.TrimSpace(e)
+
+ value, err := defineType(schemaType, e)
+ if err != nil {
+ return err
+ }
+
+ switch objectType {
+ case ARRAY:
+ param.Items.Enum = append(param.Items.Enum, value)
+ default:
+ switch paramType {
+ case "body":
+ param.Schema.Enum = append(param.Schema.Enum, value)
+ default:
+ param.Enum = append(param.Enum, value)
+ }
+ }
+ }
+
+ return nil
+}
+
+func setExtensionParam(attr string) spec.Extensions {
+ extensions := spec.Extensions{}
+
+ for _, val := range splitNotWrapped(attr, ',') {
+ parts := strings.SplitN(val, "=", 2)
+ if len(parts) == 2 {
+ extensions.Add(parts[0], parts[1])
+
+ continue
+ }
+
+ if len(parts[0]) > 0 && string(parts[0][0]) == "!" {
+ extensions.Add(parts[0][1:], false)
+
+ continue
+ }
+
+ extensions.Add(parts[0], true)
+ }
+
+ return extensions
+}
+
+func setCollectionFormatParam(param *spec.Parameter, name, schemaType, attr, commentLine string) error {
+ if schemaType == ARRAY {
+ param.CollectionFormat = TransToValidCollectionFormat(attr)
+
+ return nil
+ }
+
+ return fmt.Errorf("%s is attribute to set to an array. comment=%s got=%s", name, commentLine, schemaType)
+}
+
+func setDefault(param *spec.Parameter, schemaType string, value string) error {
+ val, err := defineType(schemaType, value)
+ if err != nil {
+ return nil // Don't set a default value if it's not valid
+ }
+
+ param.Default = val
+
+ return nil
+}
+
+func setSchemaExample(param *spec.Parameter, schemaType string, value string) error {
+ val, err := defineType(schemaType, value)
+ if err != nil {
+ return nil // Don't set a example value if it's not valid
+ }
+ // skip schema
+ if param.Schema == nil {
+ return nil
+ }
+
+ switch v := val.(type) {
+ case string:
+ // replaces \r \n \t in example string values.
+ param.Schema.Example = strings.NewReplacer(`\r`, "\r", `\n`, "\n", `\t`, "\t").Replace(v)
+ default:
+ param.Schema.Example = val
+ }
+
+ return nil
+}
+
+func setExample(param *spec.Parameter, schemaType string, value string) error {
+ val, err := defineType(schemaType, value)
+ if err != nil {
+ return nil // Don't set a example value if it's not valid
+ }
+
+ param.Example = val
+
+ return nil
+}
+
+// defineType enum value define the type (object and array unsupported).
+func defineType(schemaType string, value string) (v interface{}, err error) {
+ schemaType = TransToValidSchemeType(schemaType)
+
+ switch schemaType {
+ case STRING:
+ return value, nil
+ case NUMBER:
+ v, err = strconv.ParseFloat(value, 64)
+ if err != nil {
+ return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)
+ }
+ case INTEGER:
+ v, err = strconv.Atoi(value)
+ if err != nil {
+ return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)
+ }
+ case BOOLEAN:
+ v, err = strconv.ParseBool(value)
+ if err != nil {
+ return nil, fmt.Errorf("enum value %s can't convert to %s err: %s", value, schemaType, err)
+ }
+ default:
+ return nil, fmt.Errorf("%s is unsupported type in enum value %s", schemaType, value)
+ }
+
+ return v, nil
+}
+
+// ParseTagsComment parses comment for given `tag` comment string.
+func (operation *Operation) ParseTagsComment(commentLine string) {
+ for _, tag := range strings.Split(commentLine, ",") {
+ operation.Tags = append(operation.Tags, strings.TrimSpace(tag))
+ }
+}
+
+// ParseAcceptComment parses comment for given `accept` comment string.
+func (operation *Operation) ParseAcceptComment(commentLine string) error {
+ return parseMimeTypeList(commentLine, &operation.Consumes, "%v accept type can't be accepted")
+}
+
+// ParseProduceComment parses comment for given `produce` comment string.
+func (operation *Operation) ParseProduceComment(commentLine string) error {
+ return parseMimeTypeList(commentLine, &operation.Produces, "%v produce type can't be accepted")
+}
+
+// parseMimeTypeList parses a list of MIME Types for a comment like
+// `produce` (`Content-Type:` response header) or
+// `accept` (`Accept:` request header).
+func parseMimeTypeList(mimeTypeList string, typeList *[]string, format string) error {
+ for _, typeName := range strings.Split(mimeTypeList, ",") {
+ if mimeTypePattern.MatchString(typeName) {
+ *typeList = append(*typeList, typeName)
+
+ continue
+ }
+
+ aliasMimeType, ok := mimeTypeAliases[typeName]
+ if !ok {
+ return fmt.Errorf(format, typeName)
+ }
+
+ *typeList = append(*typeList, aliasMimeType)
+ }
+
+ return nil
+}
+
+var routerPattern = regexp.MustCompile(`^(/[\w./\-{}+:$]*)[[:blank:]]+\[(\w+)]`)
+
+// ParseRouterComment parses comment for given `router` comment string.
+func (operation *Operation) ParseRouterComment(commentLine string, deprecated bool) error {
+ matches := routerPattern.FindStringSubmatch(commentLine)
+ if len(matches) != 3 {
+ return fmt.Errorf("can not parse router comment \"%s\"", commentLine)
+ }
+
+ signature := RouteProperties{
+ Path: matches[1],
+ HTTPMethod: strings.ToUpper(matches[2]),
+ Deprecated: deprecated,
+ }
+
+ if _, ok := allMethod[signature.HTTPMethod]; !ok {
+ return fmt.Errorf("invalid method: %s", signature.HTTPMethod)
+ }
+
+ operation.RouterProperties = append(operation.RouterProperties, signature)
+
+ return nil
+}
+
+// ParseSecurityComment parses comment for given `security` comment string.
+func (operation *Operation) ParseSecurityComment(commentLine string) error {
+ if len(commentLine) == 0 {
+ operation.Security = []map[string][]string{}
+ return nil
+ }
+
+ var (
+ securityMap = make(map[string][]string)
+ securitySource = commentLine[strings.Index(commentLine, "@Security")+1:]
+ )
+
+ for _, securityOption := range strings.Split(securitySource, "||") {
+ securityOption = strings.TrimSpace(securityOption)
+
+ left, right := strings.Index(securityOption, "["), strings.Index(securityOption, "]")
+
+ if !(left == -1 && right == -1) {
+ scopes := securityOption[left+1 : right]
+
+ var options []string
+
+ for _, scope := range strings.Split(scopes, ",") {
+ options = append(options, strings.TrimSpace(scope))
+ }
+
+ securityKey := securityOption[0:left]
+ securityMap[securityKey] = append(securityMap[securityKey], options...)
+ } else {
+ securityKey := strings.TrimSpace(securityOption)
+ securityMap[securityKey] = []string{}
+ }
+ }
+
+ operation.Security = append(operation.Security, securityMap)
+
+ return nil
+}
+
+// findTypeDef attempts to find the *ast.TypeSpec for a specific type given the
+// type's name and the package's import path.
+// TODO: improve finding external pkg.
+func findTypeDef(importPath, typeName string) (*ast.TypeSpec, error) {
+ cwd, err := os.Getwd()
+ if err != nil {
+ return nil, err
+ }
+
+ conf := loader.Config{
+ ParserMode: goparser.SpuriousErrors,
+ Cwd: cwd,
+ }
+
+ conf.Import(importPath)
+
+ lprog, err := conf.Load()
+ if err != nil {
+ return nil, err
+ }
+
+ // If the pkg is vendored, the actual pkg path is going to resemble
+ // something like "{importPath}/vendor/{importPath}"
+ for k := range lprog.AllPackages {
+ realPkgPath := k.Path()
+
+ if strings.Contains(realPkgPath, "vendor/"+importPath) {
+ importPath = realPkgPath
+ }
+ }
+
+ pkgInfo := lprog.Package(importPath)
+
+ if pkgInfo == nil {
+ return nil, fmt.Errorf("package was nil")
+ }
+
+ // TODO: possibly cache pkgInfo since it's an expensive operation
+ for i := range pkgInfo.Files {
+ for _, astDeclaration := range pkgInfo.Files[i].Decls {
+ generalDeclaration, ok := astDeclaration.(*ast.GenDecl)
+ if ok && generalDeclaration.Tok == token.TYPE {
+ for _, astSpec := range generalDeclaration.Specs {
+ typeSpec, ok := astSpec.(*ast.TypeSpec)
+ if ok {
+ if typeSpec.Name.String() == typeName {
+ return typeSpec, nil
+ }
+ }
+ }
+ }
+ }
+ }
+
+ return nil, fmt.Errorf("type spec not found")
+}
+
+var responsePattern = regexp.MustCompile(`^([\w,]+)\s+([\w{}]+)\s+([\w\-.\\{}=,\[\s\]]+)\s*(".*)?`)
+
+// ResponseType{data1=Type1,data2=Type2}.
+var combinedPattern = regexp.MustCompile(`^([\w\-./\[\]]+){(.*)}$`)
+
+func (operation *Operation) parseObjectSchema(refType string, astFile *ast.File) (*spec.Schema, error) {
+ return parseObjectSchema(operation.parser, refType, astFile)
+}
+
+func parseObjectSchema(parser *Parser, refType string, astFile *ast.File) (*spec.Schema, error) {
+ switch {
+ case refType == NIL:
+ return nil, nil
+ case refType == INTERFACE:
+ return PrimitiveSchema(OBJECT), nil
+ case refType == ANY:
+ return PrimitiveSchema(OBJECT), nil
+ case IsGolangPrimitiveType(refType):
+ refType = TransToValidSchemeType(refType)
+
+ return PrimitiveSchema(refType), nil
+ case IsPrimitiveType(refType):
+ return PrimitiveSchema(refType), nil
+ case strings.HasPrefix(refType, "[]"):
+ schema, err := parseObjectSchema(parser, refType[2:], astFile)
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.ArrayProperty(schema), nil
+ case strings.HasPrefix(refType, "map["):
+ // ignore key type
+ idx := strings.Index(refType, "]")
+ if idx < 0 {
+ return nil, fmt.Errorf("invalid type: %s", refType)
+ }
+
+ refType = refType[idx+1:]
+ if refType == INTERFACE || refType == ANY {
+ return spec.MapProperty(nil), nil
+ }
+
+ schema, err := parseObjectSchema(parser, refType, astFile)
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.MapProperty(schema), nil
+ case strings.Contains(refType, "{"):
+ return parseCombinedObjectSchema(parser, refType, astFile)
+ default:
+ if parser != nil { // checking refType has existing in 'TypeDefinitions'
+ schema, err := parser.getTypeSchema(refType, astFile, true)
+ if err != nil {
+ return nil, err
+ }
+
+ return schema, nil
+ }
+
+ return RefSchema(refType), nil
+ }
+}
+
+func parseFields(s string) []string {
+ nestLevel := 0
+
+ return strings.FieldsFunc(s, func(char rune) bool {
+ if char == '{' {
+ nestLevel++
+
+ return false
+ } else if char == '}' {
+ nestLevel--
+
+ return false
+ }
+
+ return char == ',' && nestLevel == 0
+ })
+}
+
+func parseCombinedObjectSchema(parser *Parser, refType string, astFile *ast.File) (*spec.Schema, error) {
+ matches := combinedPattern.FindStringSubmatch(refType)
+ if len(matches) != 3 {
+ return nil, fmt.Errorf("invalid type: %s", refType)
+ }
+
+ schema, err := parseObjectSchema(parser, matches[1], astFile)
+ if err != nil {
+ return nil, err
+ }
+
+ fields, props := parseFields(matches[2]), map[string]spec.Schema{}
+
+ for _, field := range fields {
+ keyVal := strings.SplitN(field, "=", 2)
+ if len(keyVal) == 2 {
+ schema, err := parseObjectSchema(parser, keyVal[1], astFile)
+ if err != nil {
+ return nil, err
+ }
+
+ if schema == nil {
+ schema = PrimitiveSchema(OBJECT)
+ }
+
+ props[keyVal[0]] = *schema
+ }
+ }
+
+ if len(props) == 0 {
+ return schema, nil
+ }
+
+ if schema.Ref.GetURL() == nil && len(schema.Type) > 0 && schema.Type[0] == OBJECT && len(schema.Properties) == 0 && schema.AdditionalProperties == nil {
+ schema.Properties = props
+ return schema, nil
+ }
+
+ return spec.ComposedSchema(*schema, spec.Schema{
+ SchemaProps: spec.SchemaProps{
+ Type: []string{OBJECT},
+ Properties: props,
+ },
+ }), nil
+}
+
+func (operation *Operation) parseAPIObjectSchema(commentLine, schemaType, refType string, astFile *ast.File) (*spec.Schema, error) {
+ if strings.HasSuffix(refType, ",") && strings.Contains(refType, "[") {
+ // regexp may have broken generic syntax. find closing bracket and add it back
+ allMatchesLenOffset := strings.Index(commentLine, refType) + len(refType)
+ lostPartEndIdx := strings.Index(commentLine[allMatchesLenOffset:], "]")
+ if lostPartEndIdx >= 0 {
+ refType += commentLine[allMatchesLenOffset : allMatchesLenOffset+lostPartEndIdx+1]
+ }
+ }
+
+ switch schemaType {
+ case OBJECT:
+ if !strings.HasPrefix(refType, "[]") {
+ return operation.parseObjectSchema(refType, astFile)
+ }
+
+ refType = refType[2:]
+
+ fallthrough
+ case ARRAY:
+ schema, err := operation.parseObjectSchema(refType, astFile)
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.ArrayProperty(schema), nil
+ default:
+ return PrimitiveSchema(schemaType), nil
+ }
+}
+
+// ParseResponseComment parses comment for given `response` comment string.
+func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error {
+ matches := responsePattern.FindStringSubmatch(commentLine)
+ if len(matches) != 5 {
+ err := operation.ParseEmptyResponseComment(commentLine)
+ if err != nil {
+ return operation.ParseEmptyResponseOnly(commentLine)
+ }
+
+ return err
+ }
+
+ description := strings.Trim(matches[4], "\"")
+
+ schema, err := operation.parseAPIObjectSchema(commentLine, strings.Trim(matches[2], "{}"), strings.TrimSpace(matches[3]), astFile)
+ if err != nil {
+ return err
+ }
+
+ for _, codeStr := range strings.Split(matches[1], ",") {
+ if strings.EqualFold(codeStr, defaultTag) {
+ operation.DefaultResponse().WithSchema(schema).WithDescription(description)
+
+ continue
+ }
+
+ code, err := strconv.Atoi(codeStr)
+ if err != nil {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ resp := spec.NewResponse().WithSchema(schema).WithDescription(description)
+ if description == "" {
+ resp.WithDescription(http.StatusText(code))
+ }
+
+ operation.AddResponse(code, resp)
+ }
+
+ return nil
+}
+
+func newHeaderSpec(schemaType, description string) spec.Header {
+ return spec.Header{
+ SimpleSchema: spec.SimpleSchema{
+ Type: schemaType,
+ },
+ HeaderProps: spec.HeaderProps{
+ Description: description,
+ },
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: nil,
+ },
+ CommonValidations: spec.CommonValidations{
+ Maximum: nil,
+ ExclusiveMaximum: false,
+ Minimum: nil,
+ ExclusiveMinimum: false,
+ MaxLength: nil,
+ MinLength: nil,
+ Pattern: "",
+ MaxItems: nil,
+ MinItems: nil,
+ UniqueItems: false,
+ MultipleOf: nil,
+ Enum: nil,
+ },
+ }
+}
+
+// ParseResponseHeaderComment parses comment for given `response header` comment string.
+func (operation *Operation) ParseResponseHeaderComment(commentLine string, _ *ast.File) error {
+ matches := responsePattern.FindStringSubmatch(commentLine)
+ if len(matches) != 5 {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ header := newHeaderSpec(strings.Trim(matches[2], "{}"), strings.Trim(matches[4], "\""))
+
+ headerKey := strings.TrimSpace(matches[3])
+
+ if strings.EqualFold(matches[1], "all") {
+ if operation.Responses.Default != nil {
+ operation.Responses.Default.Headers[headerKey] = header
+ }
+
+ if operation.Responses.StatusCodeResponses != nil {
+ for code, response := range operation.Responses.StatusCodeResponses {
+ response.Headers[headerKey] = header
+ operation.Responses.StatusCodeResponses[code] = response
+ }
+ }
+
+ return nil
+ }
+
+ for _, codeStr := range strings.Split(matches[1], ",") {
+ if strings.EqualFold(codeStr, defaultTag) {
+ if operation.Responses.Default != nil {
+ operation.Responses.Default.Headers[headerKey] = header
+ }
+
+ continue
+ }
+
+ code, err := strconv.Atoi(codeStr)
+ if err != nil {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ if operation.Responses.StatusCodeResponses != nil {
+ response, responseExist := operation.Responses.StatusCodeResponses[code]
+ if responseExist {
+ response.Headers[headerKey] = header
+
+ operation.Responses.StatusCodeResponses[code] = response
+ }
+ }
+ }
+
+ return nil
+}
+
+var emptyResponsePattern = regexp.MustCompile(`([\w,]+)\s+"(.*)"`)
+
+// ParseEmptyResponseComment parse only comment out status code and description,eg: @Success 200 "it's ok".
+func (operation *Operation) ParseEmptyResponseComment(commentLine string) error {
+ matches := emptyResponsePattern.FindStringSubmatch(commentLine)
+ if len(matches) != 3 {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ description := strings.Trim(matches[2], "\"")
+
+ for _, codeStr := range strings.Split(matches[1], ",") {
+ if strings.EqualFold(codeStr, defaultTag) {
+ operation.DefaultResponse().WithDescription(description)
+
+ continue
+ }
+
+ code, err := strconv.Atoi(codeStr)
+ if err != nil {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ operation.AddResponse(code, spec.NewResponse().WithDescription(description))
+ }
+
+ return nil
+}
+
+// ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200.
+func (operation *Operation) ParseEmptyResponseOnly(commentLine string) error {
+ for _, codeStr := range strings.Split(commentLine, ",") {
+ if strings.EqualFold(codeStr, defaultTag) {
+ _ = operation.DefaultResponse()
+
+ continue
+ }
+
+ code, err := strconv.Atoi(codeStr)
+ if err != nil {
+ return fmt.Errorf("can not parse response comment \"%s\"", commentLine)
+ }
+
+ operation.AddResponse(code, spec.NewResponse().WithDescription(http.StatusText(code)))
+ }
+
+ return nil
+}
+
+// DefaultResponse return the default response member pointer.
+func (operation *Operation) DefaultResponse() *spec.Response {
+ if operation.Responses.Default == nil {
+ operation.Responses.Default = &spec.Response{
+ ResponseProps: spec.ResponseProps{
+ Description: "",
+ Headers: make(map[string]spec.Header),
+ },
+ }
+ }
+
+ return operation.Responses.Default
+}
+
+// AddResponse add a response for a code.
+func (operation *Operation) AddResponse(code int, response *spec.Response) {
+ if response.Headers == nil {
+ response.Headers = make(map[string]spec.Header)
+ }
+
+ operation.Responses.StatusCodeResponses[code] = *response
+}
+
+// createParameter returns swagger spec.Parameter for given paramType, description, paramName, schemaType, required.
+func createParameter(paramType, description, paramName, objectType, schemaType string, required bool, enums []interface{}, collectionFormat string) spec.Parameter {
+ // //five possible parameter types. query, path, body, header, form
+ result := spec.Parameter{
+ ParamProps: spec.ParamProps{
+ Name: paramName,
+ Description: description,
+ Required: required,
+ In: paramType,
+ },
+ }
+
+ if paramType == "body" {
+ return result
+ }
+
+ switch objectType {
+ case ARRAY:
+ result.Type = objectType
+ result.CollectionFormat = collectionFormat
+ result.Items = &spec.Items{
+ CommonValidations: spec.CommonValidations{
+ Enum: enums,
+ },
+ SimpleSchema: spec.SimpleSchema{
+ Type: schemaType,
+ },
+ }
+ case PRIMITIVE, OBJECT:
+ result.Type = schemaType
+ result.Enum = enums
+ }
+ return result
+}
+
+func getCodeExampleForSummary(summaryName string, dirPath string) ([]byte, error) {
+ dirEntries, err := os.ReadDir(dirPath)
+ if err != nil {
+ return nil, err
+ }
+
+ for _, entry := range dirEntries {
+ if entry.IsDir() {
+ continue
+ }
+
+ fileName := entry.Name()
+
+ if !strings.Contains(fileName, ".json") {
+ continue
+ }
+
+ if strings.Contains(fileName, summaryName) {
+ fullPath := filepath.Join(dirPath, fileName)
+
+ commentInfo, err := os.ReadFile(fullPath)
+ if err != nil {
+ return nil, fmt.Errorf("Failed to read code example file %s error: %s ", fullPath, err)
+ }
+
+ return commentInfo, nil
+ }
+ }
+
+ return nil, fmt.Errorf("unable to find code example file for tag %s in the given directory", summaryName)
+}
diff --git a/vendor/github.com/swaggo/swag/package.go b/vendor/github.com/swaggo/swag/package.go
new file mode 100644
index 0000000..6c3129e
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/package.go
@@ -0,0 +1,187 @@
+package swag
+
+import (
+ "go/ast"
+ "go/token"
+ "reflect"
+ "strconv"
+ "strings"
+)
+
+// PackageDefinitions files and definition in a package.
+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
+}
+
+// ConstVariableGlobalEvaluator an interface used to evaluate enums across packages
+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
+}
+
+// NewPackageDefinitions new a PackageDefinitions object
+func NewPackageDefinitions(name, pkgPath string) *PackageDefinitions {
+ return &PackageDefinitions{
+ Name: name,
+ Path: pkgPath,
+ Files: make(map[string]*ast.File),
+ TypeDefinitions: make(map[string]*TypeSpecDef),
+ ConstTable: make(map[string]*ConstVariable),
+ }
+}
+
+// AddFile add a file
+func (pkg *PackageDefinitions) AddFile(pkgPath string, file *ast.File) *PackageDefinitions {
+ pkg.Files[pkgPath] = file
+ return pkg
+}
+
+// AddTypeSpec add a type spec.
+func (pkg *PackageDefinitions) AddTypeSpec(name string, typeSpec *TypeSpecDef) *PackageDefinitions {
+ pkg.TypeDefinitions[name] = typeSpec
+ return pkg
+}
+
+// AddConst add a const variable.
+func (pkg *PackageDefinitions) AddConst(astFile *ast.File, valueSpec *ast.ValueSpec) *PackageDefinitions {
+ for i := 0; i < len(valueSpec.Names) && i < len(valueSpec.Values); i++ {
+ variable := &ConstVariable{
+ Name: valueSpec.Names[i],
+ Type: valueSpec.Type,
+ Value: valueSpec.Values[i],
+ Comment: valueSpec.Comment,
+ File: astFile,
+ }
+ pkg.ConstTable[valueSpec.Names[i].Name] = variable
+ pkg.OrderedConst = append(pkg.OrderedConst, variable)
+ }
+ return pkg
+}
+
+func (pkg *PackageDefinitions) evaluateConstValue(file *ast.File, iota int, expr ast.Expr, globalEvaluator ConstVariableGlobalEvaluator, recursiveStack map[string]struct{}) (interface{}, ast.Expr) {
+ switch valueExpr := expr.(type) {
+ case *ast.Ident:
+ if valueExpr.Name == "iota" {
+ return iota, nil
+ }
+ if pkg.ConstTable != nil {
+ if cv, ok := pkg.ConstTable[valueExpr.Name]; ok {
+ return globalEvaluator.EvaluateConstValue(pkg, cv, recursiveStack)
+ }
+ }
+ case *ast.SelectorExpr:
+ pkgIdent, ok := valueExpr.X.(*ast.Ident)
+ if !ok {
+ return nil, nil
+ }
+ return globalEvaluator.EvaluateConstValueByName(file, pkgIdent.Name, valueExpr.Sel.Name, recursiveStack)
+ case *ast.BasicLit:
+ switch valueExpr.Kind {
+ case token.INT:
+ // handle underscored number, such as 1_000_000
+ if strings.ContainsRune(valueExpr.Value, '_') {
+ valueExpr.Value = strings.Replace(valueExpr.Value, "_", "", -1)
+ }
+ if len(valueExpr.Value) >= 2 && valueExpr.Value[0] == '0' {
+ var start, base = 2, 8
+ switch valueExpr.Value[1] {
+ case 'x', 'X':
+ //hex
+ base = 16
+ case 'b', 'B':
+ //binary
+ base = 2
+ default:
+ //octet
+ start = 1
+ }
+ if x, err := strconv.ParseInt(valueExpr.Value[start:], base, 64); err == nil {
+ return int(x), nil
+ } else if x, err := strconv.ParseUint(valueExpr.Value[start:], base, 64); err == nil {
+ return x, nil
+ } else {
+ panic(err)
+ }
+ }
+
+ //a basic literal integer is int type in default, or must have an explicit converting type in front
+ if x, err := strconv.ParseInt(valueExpr.Value, 10, 64); err == nil {
+ return int(x), nil
+ } else if x, err := strconv.ParseUint(valueExpr.Value, 10, 64); err == nil {
+ return x, nil
+ } else {
+ panic(err)
+ }
+ case token.STRING:
+ if valueExpr.Value[0] == '`' {
+ return valueExpr.Value[1 : len(valueExpr.Value)-1], nil
+ }
+ return EvaluateEscapedString(valueExpr.Value[1 : len(valueExpr.Value)-1]), nil
+ case token.CHAR:
+ return EvaluateEscapedChar(valueExpr.Value[1 : len(valueExpr.Value)-1]), nil
+ }
+ case *ast.UnaryExpr:
+ x, evalType := pkg.evaluateConstValue(file, iota, valueExpr.X, globalEvaluator, recursiveStack)
+ if x == nil {
+ return x, evalType
+ }
+ return EvaluateUnary(x, valueExpr.Op, evalType)
+ case *ast.BinaryExpr:
+ x, evalTypex := pkg.evaluateConstValue(file, iota, valueExpr.X, globalEvaluator, recursiveStack)
+ y, evalTypey := pkg.evaluateConstValue(file, iota, valueExpr.Y, globalEvaluator, recursiveStack)
+ if x == nil || y == nil {
+ return nil, nil
+ }
+ return EvaluateBinary(x, y, valueExpr.Op, evalTypex, evalTypey)
+ case *ast.ParenExpr:
+ return pkg.evaluateConstValue(file, iota, valueExpr.X, globalEvaluator, recursiveStack)
+ case *ast.CallExpr:
+ //data conversion
+ if len(valueExpr.Args) != 1 {
+ return nil, nil
+ }
+ arg := valueExpr.Args[0]
+ if ident, ok := valueExpr.Fun.(*ast.Ident); ok {
+ name := ident.Name
+ if name == "uintptr" {
+ name = "uint"
+ }
+ value, _ := pkg.evaluateConstValue(file, iota, arg, globalEvaluator, recursiveStack)
+ if IsGolangPrimitiveType(name) {
+ value = EvaluateDataConversion(value, name)
+ return value, nil
+ } else if name == "len" {
+ return reflect.ValueOf(value).Len(), nil
+ }
+ typeDef := globalEvaluator.FindTypeSpec(name, file)
+ if typeDef == nil {
+ return nil, nil
+ }
+ return value, valueExpr.Fun
+ } else if selector, ok := valueExpr.Fun.(*ast.SelectorExpr); ok {
+ typeDef := globalEvaluator.FindTypeSpec(fullTypeName(selector.X.(*ast.Ident).Name, selector.Sel.Name), file)
+ if typeDef == nil {
+ return nil, nil
+ }
+ return arg, typeDef.TypeSpec.Type
+ }
+ }
+ return nil, nil
+}
diff --git a/vendor/github.com/swaggo/swag/packages.go b/vendor/github.com/swaggo/swag/packages.go
new file mode 100644
index 0000000..69a1b05
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/packages.go
@@ -0,0 +1,574 @@
+package swag
+
+import (
+ "fmt"
+ "go/ast"
+ goparser "go/parser"
+ "go/token"
+ "os"
+ "path/filepath"
+ "runtime"
+ "sort"
+ "strings"
+
+ "golang.org/x/tools/go/loader"
+)
+
+// PackagesDefinitions map[package import path]*PackageDefinitions.
+type PackagesDefinitions struct {
+ files map[*ast.File]*AstFileInfo
+ packages map[string]*PackageDefinitions
+ uniqueDefinitions map[string]*TypeSpecDef
+ parseDependency ParseFlag
+ debug Debugger
+}
+
+// NewPackagesDefinitions create object PackagesDefinitions.
+func NewPackagesDefinitions() *PackagesDefinitions {
+ return &PackagesDefinitions{
+ files: make(map[*ast.File]*AstFileInfo),
+ packages: make(map[string]*PackageDefinitions),
+ uniqueDefinitions: make(map[string]*TypeSpecDef),
+ }
+}
+
+// ParseFile parse a source file.
+func (pkgDefs *PackagesDefinitions) ParseFile(packageDir, path string, src interface{}, flag ParseFlag) error {
+ // positions are relative to FileSet
+ fileSet := token.NewFileSet()
+ astFile, err := goparser.ParseFile(fileSet, path, src, goparser.ParseComments)
+ if err != nil {
+ return fmt.Errorf("failed to parse file %s, error:%+v", path, err)
+ }
+ return pkgDefs.collectAstFile(fileSet, packageDir, path, astFile, flag)
+}
+
+// collectAstFile collect ast.file.
+func (pkgDefs *PackagesDefinitions) collectAstFile(fileSet *token.FileSet, packageDir, path string, astFile *ast.File, flag ParseFlag) error {
+ if pkgDefs.files == nil {
+ pkgDefs.files = make(map[*ast.File]*AstFileInfo)
+ }
+
+ if pkgDefs.packages == nil {
+ pkgDefs.packages = make(map[string]*PackageDefinitions)
+ }
+
+ // return without storing the file if we lack a packageDir
+ if packageDir == "" {
+ return nil
+ }
+
+ path, err := filepath.Abs(path)
+ if err != nil {
+ return err
+ }
+
+ dependency, ok := pkgDefs.packages[packageDir]
+ if ok {
+ // return without storing the file if it already exists
+ _, exists := dependency.Files[path]
+ if exists {
+ return nil
+ }
+
+ dependency.Files[path] = astFile
+ } else {
+ pkgDefs.packages[packageDir] = NewPackageDefinitions(astFile.Name.Name, packageDir).AddFile(path, astFile)
+ }
+
+ pkgDefs.files[astFile] = &AstFileInfo{
+ FileSet: fileSet,
+ File: astFile,
+ Path: path,
+ PackagePath: packageDir,
+ ParseFlag: flag,
+ }
+
+ return nil
+}
+
+// RangeFiles for range the collection of ast.File in alphabetic order.
+func (pkgDefs *PackagesDefinitions) RangeFiles(handle func(info *AstFileInfo) error) error {
+ sortedFiles := make([]*AstFileInfo, 0, len(pkgDefs.files))
+ for _, info := range pkgDefs.files {
+ // ignore package path prefix with 'vendor' or $GOROOT,
+ // because the router info of api will not be included these files.
+ if strings.HasPrefix(info.PackagePath, "vendor") || strings.HasPrefix(info.Path, runtime.GOROOT()) {
+ continue
+ }
+ sortedFiles = append(sortedFiles, info)
+ }
+
+ sort.Slice(sortedFiles, func(i, j int) bool {
+ return strings.Compare(sortedFiles[i].Path, sortedFiles[j].Path) < 0
+ })
+
+ for _, info := range sortedFiles {
+ err := handle(info)
+ if err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+// ParseTypes parse types
+// @Return parsed definitions.
+func (pkgDefs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error) {
+ parsedSchemas := make(map[*TypeSpecDef]*Schema)
+ for astFile, info := range pkgDefs.files {
+ pkgDefs.parseTypesFromFile(astFile, info.PackagePath, parsedSchemas)
+ pkgDefs.parseFunctionScopedTypesFromFile(astFile, info.PackagePath, parsedSchemas)
+ }
+ pkgDefs.removeAllNotUniqueTypes()
+ pkgDefs.evaluateAllConstVariables()
+ pkgDefs.collectConstEnums(parsedSchemas)
+ return parsedSchemas, nil
+}
+
+func (pkgDefs *PackagesDefinitions) parseTypesFromFile(astFile *ast.File, packagePath string, parsedSchemas map[*TypeSpecDef]*Schema) {
+ for _, astDeclaration := range astFile.Decls {
+ generalDeclaration, ok := astDeclaration.(*ast.GenDecl)
+ if !ok {
+ continue
+ }
+ if generalDeclaration.Tok == token.TYPE {
+ for _, astSpec := range generalDeclaration.Specs {
+ if typeSpec, ok := astSpec.(*ast.TypeSpec); ok {
+ typeSpecDef := &TypeSpecDef{
+ PkgPath: packagePath,
+ File: astFile,
+ TypeSpec: typeSpec,
+ }
+
+ if idt, ok := typeSpec.Type.(*ast.Ident); ok && IsGolangPrimitiveType(idt.Name) && parsedSchemas != nil {
+ parsedSchemas[typeSpecDef] = &Schema{
+ PkgPath: typeSpecDef.PkgPath,
+ Name: astFile.Name.Name,
+ Schema: PrimitiveSchema(TransToValidSchemeType(idt.Name)),
+ }
+ }
+
+ if pkgDefs.uniqueDefinitions == nil {
+ pkgDefs.uniqueDefinitions = make(map[string]*TypeSpecDef)
+ }
+
+ fullName := typeSpecDef.TypeName()
+
+ anotherTypeDef, ok := pkgDefs.uniqueDefinitions[fullName]
+ if ok {
+ if anotherTypeDef == nil {
+ typeSpecDef.NotUnique = true
+ fullName = typeSpecDef.TypeName()
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ } else if typeSpecDef.PkgPath != anotherTypeDef.PkgPath {
+ pkgDefs.uniqueDefinitions[fullName] = nil
+ anotherTypeDef.NotUnique = true
+ pkgDefs.uniqueDefinitions[anotherTypeDef.TypeName()] = anotherTypeDef
+ typeSpecDef.NotUnique = true
+ fullName = typeSpecDef.TypeName()
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ }
+ } else {
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ }
+
+ if pkgDefs.packages[typeSpecDef.PkgPath] == nil {
+ pkgDefs.packages[typeSpecDef.PkgPath] = NewPackageDefinitions(astFile.Name.Name, typeSpecDef.PkgPath).AddTypeSpec(typeSpecDef.Name(), typeSpecDef)
+ } else if _, ok = pkgDefs.packages[typeSpecDef.PkgPath].TypeDefinitions[typeSpecDef.Name()]; !ok {
+ pkgDefs.packages[typeSpecDef.PkgPath].AddTypeSpec(typeSpecDef.Name(), typeSpecDef)
+ }
+ }
+ }
+ } else if generalDeclaration.Tok == token.CONST {
+ // collect consts
+ pkgDefs.collectConstVariables(astFile, packagePath, generalDeclaration)
+ }
+ }
+}
+
+func (pkgDefs *PackagesDefinitions) parseFunctionScopedTypesFromFile(astFile *ast.File, packagePath string, parsedSchemas map[*TypeSpecDef]*Schema) {
+ for _, astDeclaration := range astFile.Decls {
+ funcDeclaration, ok := astDeclaration.(*ast.FuncDecl)
+ if ok && funcDeclaration.Body != nil {
+ for _, stmt := range funcDeclaration.Body.List {
+ if declStmt, ok := (stmt).(*ast.DeclStmt); ok {
+ if genDecl, ok := (declStmt.Decl).(*ast.GenDecl); ok && genDecl.Tok == token.TYPE {
+ for _, astSpec := range genDecl.Specs {
+ if typeSpec, ok := astSpec.(*ast.TypeSpec); ok {
+ typeSpecDef := &TypeSpecDef{
+ PkgPath: packagePath,
+ File: astFile,
+ TypeSpec: typeSpec,
+ ParentSpec: astDeclaration,
+ }
+
+ if idt, ok := typeSpec.Type.(*ast.Ident); ok && IsGolangPrimitiveType(idt.Name) && parsedSchemas != nil {
+ parsedSchemas[typeSpecDef] = &Schema{
+ PkgPath: typeSpecDef.PkgPath,
+ Name: astFile.Name.Name,
+ Schema: PrimitiveSchema(TransToValidSchemeType(idt.Name)),
+ }
+ }
+
+ if pkgDefs.uniqueDefinitions == nil {
+ pkgDefs.uniqueDefinitions = make(map[string]*TypeSpecDef)
+ }
+
+ fullName := typeSpecDef.TypeName()
+
+ anotherTypeDef, ok := pkgDefs.uniqueDefinitions[fullName]
+ if ok {
+ if anotherTypeDef == nil {
+ typeSpecDef.NotUnique = true
+ fullName = typeSpecDef.TypeName()
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ } else if typeSpecDef.PkgPath != anotherTypeDef.PkgPath {
+ pkgDefs.uniqueDefinitions[fullName] = nil
+ anotherTypeDef.NotUnique = true
+ pkgDefs.uniqueDefinitions[anotherTypeDef.TypeName()] = anotherTypeDef
+ typeSpecDef.NotUnique = true
+ fullName = typeSpecDef.TypeName()
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ }
+ } else {
+ pkgDefs.uniqueDefinitions[fullName] = typeSpecDef
+ }
+
+ if pkgDefs.packages[typeSpecDef.PkgPath] == nil {
+ pkgDefs.packages[typeSpecDef.PkgPath] = NewPackageDefinitions(astFile.Name.Name, typeSpecDef.PkgPath).AddTypeSpec(fullName, typeSpecDef)
+ } else if _, ok = pkgDefs.packages[typeSpecDef.PkgPath].TypeDefinitions[fullName]; !ok {
+ pkgDefs.packages[typeSpecDef.PkgPath].AddTypeSpec(fullName, typeSpecDef)
+ }
+ }
+ }
+
+ }
+ }
+ }
+ }
+ }
+}
+
+func (pkgDefs *PackagesDefinitions) collectConstVariables(astFile *ast.File, packagePath string, generalDeclaration *ast.GenDecl) {
+ pkg, ok := pkgDefs.packages[packagePath]
+ if !ok {
+ pkg = NewPackageDefinitions(astFile.Name.Name, packagePath)
+ pkgDefs.packages[packagePath] = pkg
+ }
+
+ var lastValueSpec *ast.ValueSpec
+ for _, astSpec := range generalDeclaration.Specs {
+ valueSpec, ok := astSpec.(*ast.ValueSpec)
+ if !ok {
+ continue
+ }
+ if len(valueSpec.Names) == 1 && len(valueSpec.Values) == 1 {
+ lastValueSpec = valueSpec
+ } else if len(valueSpec.Names) == 1 && len(valueSpec.Values) == 0 && valueSpec.Type == nil && lastValueSpec != nil {
+ valueSpec.Type = lastValueSpec.Type
+ valueSpec.Values = lastValueSpec.Values
+ }
+ pkg.AddConst(astFile, valueSpec)
+ }
+}
+
+func (pkgDefs *PackagesDefinitions) evaluateAllConstVariables() {
+ for _, pkg := range pkgDefs.packages {
+ for _, constVar := range pkg.OrderedConst {
+ pkgDefs.EvaluateConstValue(pkg, constVar, nil)
+ }
+ }
+}
+
+// EvaluateConstValue evaluate a const variable.
+func (pkgDefs *PackagesDefinitions) EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr) {
+ if expr, ok := cv.Value.(ast.Expr); ok {
+ defer func() {
+ if err := recover(); err != nil {
+ if fi, ok := pkgDefs.files[cv.File]; ok {
+ pos := fi.FileSet.Position(cv.Name.NamePos)
+ pkgDefs.debug.Printf("warning: failed to evaluate const %s at %s:%d:%d, %v", cv.Name.Name, fi.Path, pos.Line, pos.Column, err)
+ }
+ }
+ }()
+ if recursiveStack == nil {
+ recursiveStack = make(map[string]struct{})
+ }
+ fullConstName := fullTypeName(pkg.Path, cv.Name.Name)
+ if _, ok = recursiveStack[fullConstName]; ok {
+ return nil, nil
+ }
+ recursiveStack[fullConstName] = struct{}{}
+
+ value, evalType := pkg.evaluateConstValue(cv.File, cv.Name.Obj.Data.(int), expr, pkgDefs, recursiveStack)
+ if cv.Type == nil && evalType != nil {
+ cv.Type = evalType
+ }
+ if value != nil {
+ cv.Value = value
+ }
+ return value, cv.Type
+ }
+ return cv.Value, cv.Type
+}
+
+// EvaluateConstValueByName evaluate a const variable by name.
+func (pkgDefs *PackagesDefinitions) EvaluateConstValueByName(file *ast.File, pkgName, constVariableName string, recursiveStack map[string]struct{}) (interface{}, ast.Expr) {
+ matchedPkgPaths, externalPkgPaths := pkgDefs.findPackagePathFromImports(pkgName, file)
+ for _, pkgPath := range matchedPkgPaths {
+ if pkg, ok := pkgDefs.packages[pkgPath]; ok {
+ if cv, ok := pkg.ConstTable[constVariableName]; ok {
+ return pkgDefs.EvaluateConstValue(pkg, cv, recursiveStack)
+ }
+ }
+ }
+ if pkgDefs.parseDependency > 0 {
+ for _, pkgPath := range externalPkgPaths {
+ if err := pkgDefs.loadExternalPackage(pkgPath); err == nil {
+ if pkg, ok := pkgDefs.packages[pkgPath]; ok {
+ if cv, ok := pkg.ConstTable[constVariableName]; ok {
+ return pkgDefs.EvaluateConstValue(pkg, cv, recursiveStack)
+ }
+ }
+ }
+ }
+ }
+ return nil, nil
+}
+
+func (pkgDefs *PackagesDefinitions) collectConstEnums(parsedSchemas map[*TypeSpecDef]*Schema) {
+ for _, pkg := range pkgDefs.packages {
+ for _, constVar := range pkg.OrderedConst {
+ if constVar.Type == nil {
+ continue
+ }
+ ident, ok := constVar.Type.(*ast.Ident)
+ if !ok || IsGolangPrimitiveType(ident.Name) {
+ continue
+ }
+ typeDef, ok := pkg.TypeDefinitions[ident.Name]
+ if !ok {
+ continue
+ }
+
+ //delete it from parsed schemas, and will parse it again
+ if _, ok = parsedSchemas[typeDef]; ok {
+ delete(parsedSchemas, typeDef)
+ }
+
+ if typeDef.Enums == nil {
+ typeDef.Enums = make([]EnumValue, 0)
+ }
+
+ name := constVar.Name.Name
+ if _, ok = constVar.Value.(ast.Expr); ok {
+ continue
+ }
+
+ enumValue := EnumValue{
+ key: name,
+ Value: constVar.Value,
+ }
+ if constVar.Comment != nil && len(constVar.Comment.List) > 0 {
+ enumValue.Comment = constVar.Comment.List[0].Text
+ enumValue.Comment = strings.TrimPrefix(enumValue.Comment, "//")
+ enumValue.Comment = strings.TrimPrefix(enumValue.Comment, "/*")
+ enumValue.Comment = strings.TrimSuffix(enumValue.Comment, "*/")
+ enumValue.Comment = strings.TrimSpace(enumValue.Comment)
+ }
+ typeDef.Enums = append(typeDef.Enums, enumValue)
+ }
+ }
+}
+
+func (pkgDefs *PackagesDefinitions) removeAllNotUniqueTypes() {
+ for key, ud := range pkgDefs.uniqueDefinitions {
+ if ud == nil {
+ delete(pkgDefs.uniqueDefinitions, key)
+ }
+ }
+}
+
+func (pkgDefs *PackagesDefinitions) findTypeSpec(pkgPath string, typeName string) *TypeSpecDef {
+ if pkgDefs.packages == nil {
+ return nil
+ }
+
+ pd, found := pkgDefs.packages[pkgPath]
+ if found {
+ typeSpec, ok := pd.TypeDefinitions[typeName]
+ if ok {
+ return typeSpec
+ }
+ }
+
+ return nil
+}
+
+func (pkgDefs *PackagesDefinitions) loadExternalPackage(importPath string) error {
+ cwd, err := os.Getwd()
+ if err != nil {
+ return err
+ }
+
+ conf := loader.Config{
+ ParserMode: goparser.ParseComments,
+ Cwd: cwd,
+ }
+
+ conf.Import(importPath)
+
+ loaderProgram, err := conf.Load()
+ if err != nil {
+ return err
+ }
+
+ for _, info := range loaderProgram.AllPackages {
+ pkgPath := strings.TrimPrefix(info.Pkg.Path(), "vendor/")
+ for _, astFile := range info.Files {
+ pkgDefs.parseTypesFromFile(astFile, pkgPath, nil)
+ }
+ }
+
+ return nil
+}
+
+// findPackagePathFromImports finds out the package path of a package via ranging imports of an ast.File
+// @pkg the name of the target package
+// @file current ast.File in which to search imports
+// @return the package paths of a package of @pkg.
+func (pkgDefs *PackagesDefinitions) findPackagePathFromImports(pkg string, file *ast.File) (matchedPkgPaths, externalPkgPaths []string) {
+ if file == nil {
+ return
+ }
+
+ if strings.ContainsRune(pkg, '.') {
+ pkg = strings.Split(pkg, ".")[0]
+ }
+
+ matchLastPathPart := func(pkgPath string) bool {
+ paths := strings.Split(pkgPath, "/")
+ return paths[len(paths)-1] == pkg
+ }
+
+ // prior to match named package
+ for _, imp := range file.Imports {
+ path := strings.Trim(imp.Path.Value, `"`)
+ if imp.Name != nil {
+ if imp.Name.Name == pkg {
+ // if name match, break loop and return
+ _, ok := pkgDefs.packages[path]
+ if ok {
+ matchedPkgPaths = []string{path}
+ externalPkgPaths = nil
+ } else {
+ externalPkgPaths = []string{path}
+ matchedPkgPaths = nil
+ }
+ break
+ } else if imp.Name.Name == "_" && len(pkg) > 0 {
+ //for unused types
+ pd, ok := pkgDefs.packages[path]
+ if ok {
+ if pd.Name == pkg {
+ matchedPkgPaths = append(matchedPkgPaths, path)
+ }
+ } else if matchLastPathPart(path) {
+ externalPkgPaths = append(externalPkgPaths, path)
+ }
+ } else if imp.Name.Name == "." && len(pkg) == 0 {
+ _, ok := pkgDefs.packages[path]
+ if ok {
+ matchedPkgPaths = append(matchedPkgPaths, path)
+ } else if len(pkg) == 0 || matchLastPathPart(path) {
+ externalPkgPaths = append(externalPkgPaths, path)
+ }
+ }
+ } else if pkgDefs.packages != nil && len(pkg) > 0 {
+ pd, ok := pkgDefs.packages[path]
+ if ok {
+ if pd.Name == pkg {
+ matchedPkgPaths = append(matchedPkgPaths, path)
+ }
+ } else if matchLastPathPart(path) {
+ externalPkgPaths = append(externalPkgPaths, path)
+ }
+ }
+ }
+
+ if len(pkg) == 0 || file.Name.Name == pkg {
+ matchedPkgPaths = append(matchedPkgPaths, pkgDefs.files[file].PackagePath)
+ }
+
+ return
+}
+
+func (pkgDefs *PackagesDefinitions) findTypeSpecFromPackagePaths(matchedPkgPaths, externalPkgPaths []string, name string) (typeDef *TypeSpecDef) {
+ if pkgDefs.parseDependency > 0 {
+ for _, pkgPath := range externalPkgPaths {
+ if err := pkgDefs.loadExternalPackage(pkgPath); err == nil {
+ typeDef = pkgDefs.findTypeSpec(pkgPath, name)
+ if typeDef != nil {
+ return typeDef
+ }
+ }
+ }
+ }
+
+ for _, pkgPath := range matchedPkgPaths {
+ typeDef = pkgDefs.findTypeSpec(pkgPath, name)
+ if typeDef != nil {
+ return typeDef
+ }
+ }
+
+ return typeDef
+}
+
+// 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 (pkgDefs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef {
+ if IsGolangPrimitiveType(typeName) {
+ return nil
+ }
+
+ if file == nil { // for test
+ return pkgDefs.uniqueDefinitions[typeName]
+ }
+
+ parts := strings.Split(strings.Split(typeName, "[")[0], ".")
+ if len(parts) > 1 {
+ pkgPaths, externalPkgPaths := pkgDefs.findPackagePathFromImports(parts[0], file)
+ if len(externalPkgPaths) == 0 || pkgDefs.parseDependency == ParseNone {
+ typeDef, ok := pkgDefs.uniqueDefinitions[typeName]
+ if ok {
+ return typeDef
+ }
+ }
+ typeDef := pkgDefs.findTypeSpecFromPackagePaths(pkgPaths, externalPkgPaths, parts[1])
+ return pkgDefs.parametrizeGenericType(file, typeDef, typeName)
+ }
+
+ typeDef, ok := pkgDefs.uniqueDefinitions[fullTypeName(file.Name.Name, typeName)]
+ if ok {
+ return typeDef
+ }
+
+ //in case that comment //@name renamed the type with a name without a dot
+ typeDef, ok = pkgDefs.uniqueDefinitions[typeName]
+ if ok {
+ return typeDef
+ }
+
+ name := parts[0]
+ typeDef, ok = pkgDefs.uniqueDefinitions[fullTypeName(file.Name.Name, name)]
+ if !ok {
+ pkgPaths, externalPkgPaths := pkgDefs.findPackagePathFromImports("", file)
+ typeDef = pkgDefs.findTypeSpecFromPackagePaths(pkgPaths, externalPkgPaths, name)
+ }
+ return pkgDefs.parametrizeGenericType(file, typeDef, typeName)
+}
diff --git a/vendor/github.com/swaggo/swag/parser.go b/vendor/github.com/swaggo/swag/parser.go
new file mode 100644
index 0000000..604f827
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/parser.go
@@ -0,0 +1,1835 @@
+package swag
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "go/ast"
+ "go/build"
+ goparser "go/parser"
+ "go/token"
+ "log"
+ "net/http"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "reflect"
+ "sort"
+ "strconv"
+ "strings"
+
+ "github.com/KyleBanks/depth"
+ "github.com/go-openapi/spec"
+)
+
+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"
+
+ idAttr = "@id"
+ acceptAttr = "@accept"
+ produceAttr = "@produce"
+ paramAttr = "@param"
+ successAttr = "@success"
+ failureAttr = "@failure"
+ responseAttr = "@response"
+ headerAttr = "@header"
+ tagsAttr = "@tags"
+ routerAttr = "@router"
+ deprecatedRouterAttr = "@deprecatedrouter"
+ summaryAttr = "@summary"
+ deprecatedAttr = "@deprecated"
+ securityAttr = "@security"
+ titleAttr = "@title"
+ conNameAttr = "@contact.name"
+ conURLAttr = "@contact.url"
+ conEmailAttr = "@contact.email"
+ licNameAttr = "@license.name"
+ licURLAttr = "@license.url"
+ versionAttr = "@version"
+ descriptionAttr = "@description"
+ descriptionMarkdownAttr = "@description.markdown"
+ secBasicAttr = "@securitydefinitions.basic"
+ secAPIKeyAttr = "@securitydefinitions.apikey"
+ secApplicationAttr = "@securitydefinitions.oauth2.application"
+ secImplicitAttr = "@securitydefinitions.oauth2.implicit"
+ secPasswordAttr = "@securitydefinitions.oauth2.password"
+ secAccessCodeAttr = "@securitydefinitions.oauth2.accesscode"
+ tosAttr = "@termsofservice"
+ extDocsDescAttr = "@externaldocs.description"
+ extDocsURLAttr = "@externaldocs.url"
+ xCodeSamplesAttr = "@x-codesamples"
+ scopeAttrPrefix = "@scope."
+ stateAttr = "@state"
+)
+
+// ParseFlag determine what to parse
+type ParseFlag int
+
+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
+)
+
+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")
+)
+
+var allMethod = map[string]struct{}{
+ http.MethodGet: {},
+ http.MethodPut: {},
+ http.MethodPost: {},
+ http.MethodDelete: {},
+ http.MethodOptions: {},
+ http.MethodHead: {},
+ http.MethodPatch: {},
+}
+
+// Parser implements a parser for Go source files.
+type Parser struct {
+ // swagger represents the root document object for the API specification
+ swagger *spec.Swagger
+
+ // packages store entities of APIs, definitions, file, package path etc. and their relations
+ packages *PackagesDefinitions
+
+ // parsedSchemas store schemas which have been parsed from ast.TypeSpec
+ parsedSchemas map[*TypeSpecDef]*Schema
+
+ // outputSchemas store schemas which will be export to swagger
+ outputSchemas map[*TypeSpecDef]*Schema
+
+ // 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
+
+ // structStack stores full names of the structures that were already parsed or are being parsed now
+ structStack []*TypeSpecDef
+
+ // markdownFileDir holds the path to the folder, where markdown files are stored
+ markdownFileDir string
+
+ // codeExampleFilesDir holds path to the folder, where code example files are stored
+ codeExampleFilesDir string
+
+ // collectionFormatInQuery set the default collectionFormat otherwise then 'csv' for array in query params
+ collectionFormatInQuery string
+
+ // excludes excludes dirs and files in SearchDir
+ excludes map[string]struct{}
+
+ // packagePrefix is a list of package path prefixes, packages that do not
+ // match any one of them will be excluded when searching.
+ packagePrefix []string
+
+ // tells parser to include only specific extension
+ parseExtension string
+
+ // debugging output goes here
+ debug Debugger
+
+ // fieldParserFactory create FieldParser
+ fieldParserFactory FieldParserFactory
+
+ // Overrides allows global replacements of types. A blank replacement will be skipped.
+ Overrides map[string]string
+
+ // parseGoList whether swag use go list to parse dependency
+ parseGoList bool
+
+ // tags to filter the APIs after
+ tags map[string]struct{}
+
+ // HostState is the state of the host
+ HostState string
+}
+
+// FieldParserFactory create FieldParser.
+type FieldParserFactory func(ps *Parser, field *ast.Field) FieldParser
+
+// FieldParser parse struct field.
+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)
+}
+
+// Debugger is the interface that wraps the basic Printf method.
+type Debugger interface {
+ Printf(format string, v ...interface{})
+}
+
+// New creates a new Parser with default properties.
+func New(options ...func(*Parser)) *Parser {
+ parser := &Parser{
+ swagger: &spec.Swagger{
+ SwaggerProps: spec.SwaggerProps{
+ Info: &spec.Info{
+ InfoProps: spec.InfoProps{
+ Contact: &spec.ContactInfo{},
+ License: nil,
+ },
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: spec.Extensions{},
+ },
+ },
+ Paths: &spec.Paths{
+ Paths: make(map[string]spec.PathItem),
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: nil,
+ },
+ },
+ Definitions: make(map[string]spec.Schema),
+ SecurityDefinitions: make(map[string]*spec.SecurityScheme),
+ },
+ VendorExtensible: spec.VendorExtensible{
+ Extensions: nil,
+ },
+ },
+ packages: NewPackagesDefinitions(),
+ debug: log.New(os.Stdout, "", log.LstdFlags),
+ parsedSchemas: make(map[*TypeSpecDef]*Schema),
+ outputSchemas: make(map[*TypeSpecDef]*Schema),
+ excludes: make(map[string]struct{}),
+ tags: make(map[string]struct{}),
+ fieldParserFactory: newTagBaseFieldParser,
+ Overrides: make(map[string]string),
+ }
+
+ for _, option := range options {
+ option(parser)
+ }
+
+ parser.packages.debug = parser.debug
+
+ return parser
+}
+
+// SetParseDependency sets whether to parse the dependent packages.
+func SetParseDependency(parseDependency int) func(*Parser) {
+ return func(p *Parser) {
+ p.ParseDependency = ParseFlag(parseDependency)
+ if p.packages != nil {
+ p.packages.parseDependency = p.ParseDependency
+ }
+ }
+}
+
+// SetMarkdownFileDirectory sets the directory to search for markdown files.
+func SetMarkdownFileDirectory(directoryPath string) func(*Parser) {
+ return func(p *Parser) {
+ p.markdownFileDir = directoryPath
+ }
+}
+
+// SetCodeExamplesDirectory sets the directory to search for code example files.
+func SetCodeExamplesDirectory(directoryPath string) func(*Parser) {
+ return func(p *Parser) {
+ p.codeExampleFilesDir = directoryPath
+ }
+}
+
+// SetExcludedDirsAndFiles sets directories and files to be excluded when searching.
+func SetExcludedDirsAndFiles(excludes string) func(*Parser) {
+ return func(p *Parser) {
+ for _, f := range strings.Split(excludes, ",") {
+ f = strings.TrimSpace(f)
+ if f != "" {
+ f = filepath.Clean(f)
+ p.excludes[f] = struct{}{}
+ }
+ }
+ }
+}
+
+// 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 SetPackagePrefix(packagePrefix string) func(*Parser) {
+ return func(p *Parser) {
+ for _, f := range strings.Split(packagePrefix, ",") {
+ f = strings.TrimSpace(f)
+ if f != "" {
+ p.packagePrefix = append(p.packagePrefix, f)
+ }
+ }
+ }
+}
+
+// SetTags sets the tags to be included
+func SetTags(include string) func(*Parser) {
+ return func(p *Parser) {
+ for _, f := range strings.Split(include, ",") {
+ f = strings.TrimSpace(f)
+ if f != "" {
+ p.tags[f] = struct{}{}
+ }
+ }
+ }
+}
+
+// SetParseExtension parses only those operations which match given extension
+func SetParseExtension(parseExtension string) func(*Parser) {
+ return func(p *Parser) {
+ p.parseExtension = parseExtension
+ }
+}
+
+// SetStrict sets whether swag should error or warn when it detects cases which are most likely user errors.
+func SetStrict(strict bool) func(*Parser) {
+ return func(p *Parser) {
+ p.Strict = strict
+ }
+}
+
+// SetDebugger allows the use of user-defined implementations.
+func SetDebugger(logger Debugger) func(parser *Parser) {
+ return func(p *Parser) {
+ if logger != nil {
+ p.debug = logger
+ }
+ }
+}
+
+// SetFieldParserFactory allows the use of user-defined implementations.
+func SetFieldParserFactory(factory FieldParserFactory) func(parser *Parser) {
+ return func(p *Parser) {
+ p.fieldParserFactory = factory
+ }
+}
+
+// SetOverrides allows the use of user-defined global type overrides.
+func SetOverrides(overrides map[string]string) func(parser *Parser) {
+ return func(p *Parser) {
+ for k, v := range overrides {
+ p.Overrides[k] = v
+ }
+ }
+}
+
+// SetCollectionFormat set default collection format
+func SetCollectionFormat(collectionFormat string) func(*Parser) {
+ return func(p *Parser) {
+ p.collectionFormatInQuery = collectionFormat
+ }
+}
+
+// ParseUsingGoList sets whether swag use go list to parse dependency
+func ParseUsingGoList(enabled bool) func(parser *Parser) {
+ return func(p *Parser) {
+ p.parseGoList = enabled
+ }
+}
+
+// ParseAPI parses general api info for given searchDir and mainAPIFile.
+func (parser *Parser) ParseAPI(searchDir string, mainAPIFile string, parseDepth int) error {
+ return parser.ParseAPIMultiSearchDir([]string{searchDir}, mainAPIFile, parseDepth)
+}
+
+// skipPackageByPrefix returns true the given pkgpath does not match
+// any user-defined package path prefixes.
+func (parser *Parser) skipPackageByPrefix(pkgpath string) bool {
+ if len(parser.packagePrefix) == 0 {
+ return false
+ }
+ for _, prefix := range parser.packagePrefix {
+ if strings.HasPrefix(pkgpath, prefix) {
+ return false
+ }
+ }
+ return true
+}
+
+// ParseAPIMultiSearchDir is like ParseAPI but for multiple search dirs.
+func (parser *Parser) ParseAPIMultiSearchDir(searchDirs []string, mainAPIFile string, parseDepth int) error {
+ for _, searchDir := range searchDirs {
+ parser.debug.Printf("Generate general API Info, search dir:%s", searchDir)
+
+ packageDir, err := getPkgName(searchDir)
+ if err != nil {
+ parser.debug.Printf("warning: failed to get package name in dir: %s, error: %s", searchDir, err.Error())
+ }
+
+ err = parser.getAllGoFileInfo(packageDir, searchDir)
+ if err != nil {
+ return err
+ }
+ }
+
+ absMainAPIFilePath, err := filepath.Abs(filepath.Join(searchDirs[0], mainAPIFile))
+ if err != nil {
+ return err
+ }
+
+ // Use 'go list' command instead of depth.Resolve()
+ if parser.ParseDependency > 0 {
+ if parser.parseGoList {
+ pkgs, err := listPackages(context.Background(), filepath.Dir(absMainAPIFilePath), nil, "-deps")
+ if err != nil {
+ return fmt.Errorf("pkg %s cannot find all dependencies, %s", filepath.Dir(absMainAPIFilePath), err)
+ }
+
+ length := len(pkgs)
+ for i := 0; i < length; i++ {
+ err := parser.getAllGoFileInfoFromDepsByList(pkgs[i], parser.ParseDependency)
+ if err != nil {
+ return err
+ }
+ }
+ } else {
+ var t depth.Tree
+ t.ResolveInternal = true
+ t.MaxDepth = parseDepth
+
+ pkgName, err := getPkgName(filepath.Dir(absMainAPIFilePath))
+ if err != nil {
+ return err
+ }
+
+ err = t.Resolve(pkgName)
+ if err != nil {
+ return fmt.Errorf("pkg %s cannot find all dependencies, %s", pkgName, err)
+ }
+ for i := 0; i < len(t.Root.Deps); i++ {
+ err := parser.getAllGoFileInfoFromDeps(&t.Root.Deps[i], parser.ParseDependency)
+ if err != nil {
+ return err
+ }
+ }
+ }
+ }
+
+ err = parser.ParseGeneralAPIInfo(absMainAPIFilePath)
+ if err != nil {
+ return err
+ }
+
+ parser.parsedSchemas, err = parser.packages.ParseTypes()
+ if err != nil {
+ return err
+ }
+
+ err = parser.packages.RangeFiles(parser.ParseRouterAPIInfo)
+ if err != nil {
+ return err
+ }
+
+ return parser.checkOperationIDUniqueness()
+}
+
+func getPkgName(searchDir string) (string, error) {
+ cmd := exec.Command("go", "list", "-f={{.ImportPath}}")
+ cmd.Dir = searchDir
+
+ var stdout, stderr strings.Builder
+
+ cmd.Stdout = &stdout
+ cmd.Stderr = &stderr
+
+ if err := cmd.Run(); err != nil {
+ return "", fmt.Errorf("execute go list command, %s, stdout:%s, stderr:%s", err, stdout.String(), stderr.String())
+ }
+
+ outStr, _ := stdout.String(), stderr.String()
+
+ if outStr[0] == '_' { // will shown like _/{GOPATH}/src/{YOUR_PACKAGE} when NOT enable GO MODULE.
+ outStr = strings.TrimPrefix(outStr, "_"+build.Default.GOPATH+"/src/")
+ }
+
+ f := strings.Split(outStr, "\n")
+
+ outStr = f[0]
+
+ return outStr, nil
+}
+
+// ParseGeneralAPIInfo parses general api info for given mainAPIFile path.
+func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error {
+ fileTree, err := goparser.ParseFile(token.NewFileSet(), mainAPIFile, nil, goparser.ParseComments)
+ if err != nil {
+ return fmt.Errorf("cannot parse source files %s: %s", mainAPIFile, err)
+ }
+
+ parser.swagger.Swagger = "2.0"
+
+ for _, comment := range fileTree.Comments {
+ comments := strings.Split(comment.Text(), "\n")
+ if !isGeneralAPIComment(comments) {
+ continue
+ }
+
+ err = parseGeneralAPIInfo(parser, comments)
+ if err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+func parseGeneralAPIInfo(parser *Parser, comments []string) error {
+ previousAttribute := ""
+
+ // parsing classic meta data model
+ for line := 0; line < len(comments); line++ {
+ commentLine := comments[line]
+ commentLine = strings.TrimSpace(commentLine)
+ if len(commentLine) == 0 {
+ continue
+ }
+ fields := FieldsByAnySpace(commentLine, 2)
+
+ attribute := fields[0]
+ var value string
+ if len(fields) > 1 {
+ value = fields[1]
+ }
+
+ switch attr := strings.ToLower(attribute); attr {
+ case versionAttr, titleAttr, tosAttr, licNameAttr, licURLAttr, conNameAttr, conURLAttr, conEmailAttr:
+ setSwaggerInfo(parser.swagger, attr, value)
+ case descriptionAttr:
+ if previousAttribute == attribute {
+ parser.swagger.Info.Description += "\n" + value
+
+ continue
+ }
+
+ setSwaggerInfo(parser.swagger, attr, value)
+ case descriptionMarkdownAttr:
+ commentInfo, err := getMarkdownForTag("api", parser.markdownFileDir)
+ if err != nil {
+ return err
+ }
+
+ setSwaggerInfo(parser.swagger, descriptionAttr, string(commentInfo))
+
+ case "@host":
+ parser.swagger.Host = value
+ case "@hoststate":
+ fields = FieldsByAnySpace(commentLine, 3)
+ if len(fields) != 3 {
+ return fmt.Errorf("%s needs 3 arguments", attribute)
+ }
+ if parser.HostState == fields[1] {
+ parser.swagger.Host = fields[2]
+ }
+ case "@basepath":
+ parser.swagger.BasePath = value
+
+ case acceptAttr:
+ err := parser.ParseAcceptComment(value)
+ if err != nil {
+ return err
+ }
+ case produceAttr:
+ err := parser.ParseProduceComment(value)
+ if err != nil {
+ return err
+ }
+ case "@schemes":
+ parser.swagger.Schemes = strings.Split(value, " ")
+ case "@tag.name":
+ parser.swagger.Tags = append(parser.swagger.Tags, spec.Tag{
+ TagProps: spec.TagProps{
+ Name: value,
+ },
+ })
+ case "@tag.description":
+ tag := parser.swagger.Tags[len(parser.swagger.Tags)-1]
+ tag.TagProps.Description = value
+ replaceLastTag(parser.swagger.Tags, tag)
+ case "@tag.description.markdown":
+ tag := parser.swagger.Tags[len(parser.swagger.Tags)-1]
+
+ commentInfo, err := getMarkdownForTag(tag.TagProps.Name, parser.markdownFileDir)
+ if err != nil {
+ return err
+ }
+
+ tag.TagProps.Description = string(commentInfo)
+ replaceLastTag(parser.swagger.Tags, tag)
+ case "@tag.docs.url":
+ tag := parser.swagger.Tags[len(parser.swagger.Tags)-1]
+ tag.TagProps.ExternalDocs = &spec.ExternalDocumentation{
+ URL: value,
+ Description: "",
+ }
+
+ replaceLastTag(parser.swagger.Tags, tag)
+ case "@tag.docs.description":
+ tag := parser.swagger.Tags[len(parser.swagger.Tags)-1]
+ if tag.TagProps.ExternalDocs == nil {
+ return fmt.Errorf("%s needs to come after a @tags.docs.url", attribute)
+ }
+
+ tag.TagProps.ExternalDocs.Description = value
+ replaceLastTag(parser.swagger.Tags, tag)
+
+ case secBasicAttr, secAPIKeyAttr, secApplicationAttr, secImplicitAttr, secPasswordAttr, secAccessCodeAttr:
+ scheme, err := parseSecAttributes(attribute, comments, &line)
+ if err != nil {
+ return err
+ }
+
+ parser.swagger.SecurityDefinitions[value] = scheme
+
+ case securityAttr:
+ parser.swagger.Security = append(parser.swagger.Security, parseSecurity(value))
+
+ case "@query.collection.format":
+ parser.collectionFormatInQuery = TransToValidCollectionFormat(value)
+
+ case extDocsDescAttr, extDocsURLAttr:
+ if parser.swagger.ExternalDocs == nil {
+ parser.swagger.ExternalDocs = new(spec.ExternalDocumentation)
+ }
+ switch attr {
+ case extDocsDescAttr:
+ parser.swagger.ExternalDocs.Description = value
+ case extDocsURLAttr:
+ parser.swagger.ExternalDocs.URL = value
+ }
+
+ default:
+ if strings.HasPrefix(attribute, "@x-") {
+ extensionName := attribute[1:]
+
+ extExistsInSecurityDef := false
+ // for each security definition
+ for _, v := range parser.swagger.SecurityDefinitions {
+ // check if extension exists
+ _, extExistsInSecurityDef = v.VendorExtensible.Extensions.GetString(extensionName)
+ // if it exists in at least one, then we stop iterating
+ if extExistsInSecurityDef {
+ break
+ }
+ }
+
+ // if it is present on security def, don't add it again
+ if extExistsInSecurityDef {
+ break
+ }
+
+ if len(value) == 0 {
+ return fmt.Errorf("annotation %s need a value", attribute)
+ }
+
+ var valueJSON interface{}
+ err := json.Unmarshal([]byte(value), &valueJSON)
+ if err != nil {
+ return fmt.Errorf("annotation %s need a valid json value", attribute)
+ }
+
+ if strings.Contains(extensionName, "logo") {
+ parser.swagger.Info.Extensions.Add(extensionName, valueJSON)
+ } else {
+ if parser.swagger.Extensions == nil {
+ parser.swagger.Extensions = make(map[string]interface{})
+ }
+
+ parser.swagger.Extensions[attribute[1:]] = valueJSON
+ }
+ }
+ }
+
+ previousAttribute = attribute
+ }
+
+ return nil
+}
+
+func setSwaggerInfo(swagger *spec.Swagger, attribute, value string) {
+ switch attribute {
+ case versionAttr:
+ swagger.Info.Version = value
+ case titleAttr:
+ swagger.Info.Title = value
+ case tosAttr:
+ swagger.Info.TermsOfService = value
+ case descriptionAttr:
+ swagger.Info.Description = value
+ case conNameAttr:
+ swagger.Info.Contact.Name = value
+ case conEmailAttr:
+ swagger.Info.Contact.Email = value
+ case conURLAttr:
+ swagger.Info.Contact.URL = value
+ case licNameAttr:
+ swagger.Info.License = initIfEmpty(swagger.Info.License)
+ swagger.Info.License.Name = value
+ case licURLAttr:
+ swagger.Info.License = initIfEmpty(swagger.Info.License)
+ swagger.Info.License.URL = value
+ }
+}
+
+func parseSecAttributes(context string, lines []string, index *int) (*spec.SecurityScheme, error) {
+ const (
+ in = "@in"
+ name = "@name"
+ descriptionAttr = "@description"
+ tokenURL = "@tokenurl"
+ authorizationURL = "@authorizationurl"
+ )
+
+ var search []string
+
+ attribute := strings.ToLower(FieldsByAnySpace(lines[*index], 2)[0])
+ switch attribute {
+ case secBasicAttr:
+ return spec.BasicAuth(), nil
+ case secAPIKeyAttr:
+ search = []string{in, name}
+ case secApplicationAttr, secPasswordAttr:
+ search = []string{tokenURL}
+ case secImplicitAttr:
+ search = []string{authorizationURL}
+ case secAccessCodeAttr:
+ search = []string{tokenURL, authorizationURL}
+ }
+
+ // For the first line we get the attributes in the context parameter, so we skip to the next one
+ *index++
+
+ attrMap, scopes := make(map[string]string), make(map[string]string)
+ extensions, description := make(map[string]interface{}), ""
+
+loopline:
+ for ; *index < len(lines); *index++ {
+ v := strings.TrimSpace(lines[*index])
+ if len(v) == 0 {
+ continue
+ }
+
+ fields := FieldsByAnySpace(v, 2)
+ securityAttr := strings.ToLower(fields[0])
+ var value string
+ if len(fields) > 1 {
+ value = fields[1]
+ }
+
+ for _, findterm := range search {
+ if securityAttr == findterm {
+ attrMap[securityAttr] = value
+ continue loopline
+ }
+ }
+
+ if isExists, err := isExistsScope(securityAttr); err != nil {
+ return nil, err
+ } else if isExists {
+ scopes[securityAttr[len(scopeAttrPrefix):]] = value
+ continue
+ }
+
+ if strings.HasPrefix(securityAttr, "@x-") {
+ // Add the custom attribute without the @
+ extensions[securityAttr[1:]] = value
+ continue
+ }
+
+ // Not mandatory field
+ if securityAttr == descriptionAttr {
+ description = value
+ }
+
+ // next securityDefinitions
+ if strings.Index(securityAttr, "@securitydefinitions.") == 0 {
+ // Go back to the previous line and break
+ *index--
+
+ break
+ }
+ }
+
+ if len(attrMap) != len(search) {
+ return nil, fmt.Errorf("%s is %v required", context, search)
+ }
+
+ var scheme *spec.SecurityScheme
+
+ switch attribute {
+ case secAPIKeyAttr:
+ scheme = spec.APIKeyAuth(attrMap[name], attrMap[in])
+ case secApplicationAttr:
+ scheme = spec.OAuth2Application(attrMap[tokenURL])
+ case secImplicitAttr:
+ scheme = spec.OAuth2Implicit(attrMap[authorizationURL])
+ case secPasswordAttr:
+ scheme = spec.OAuth2Password(attrMap[tokenURL])
+ case secAccessCodeAttr:
+ scheme = spec.OAuth2AccessToken(attrMap[authorizationURL], attrMap[tokenURL])
+ }
+
+ scheme.Description = description
+
+ for extKey, extValue := range extensions {
+ scheme.AddExtension(extKey, extValue)
+ }
+
+ for scope, scopeDescription := range scopes {
+ scheme.AddScope(scope, scopeDescription)
+ }
+
+ return scheme, nil
+}
+
+func parseSecurity(commentLine string) map[string][]string {
+ securityMap := make(map[string][]string)
+
+ for _, securityOption := range strings.Split(commentLine, "||") {
+ securityOption = strings.TrimSpace(securityOption)
+
+ left, right := strings.Index(securityOption, "["), strings.Index(securityOption, "]")
+
+ if !(left == -1 && right == -1) {
+ scopes := securityOption[left+1 : right]
+
+ var options []string
+
+ for _, scope := range strings.Split(scopes, ",") {
+ options = append(options, strings.TrimSpace(scope))
+ }
+
+ securityKey := securityOption[0:left]
+ securityMap[securityKey] = append(securityMap[securityKey], options...)
+ } else {
+ securityKey := strings.TrimSpace(securityOption)
+ securityMap[securityKey] = []string{}
+ }
+ }
+
+ return securityMap
+}
+
+func initIfEmpty(license *spec.License) *spec.License {
+ if license == nil {
+ return new(spec.License)
+ }
+
+ return license
+}
+
+// ParseAcceptComment parses comment for given `accept` comment string.
+func (parser *Parser) ParseAcceptComment(commentLine string) error {
+ return parseMimeTypeList(commentLine, &parser.swagger.Consumes, "%v accept type can't be accepted")
+}
+
+// ParseProduceComment parses comment for given `produce` comment string.
+func (parser *Parser) ParseProduceComment(commentLine string) error {
+ return parseMimeTypeList(commentLine, &parser.swagger.Produces, "%v produce type can't be accepted")
+}
+
+func isGeneralAPIComment(comments []string) bool {
+ for _, commentLine := range comments {
+ commentLine = strings.TrimSpace(commentLine)
+ if len(commentLine) == 0 {
+ continue
+ }
+ attribute := strings.ToLower(FieldsByAnySpace(commentLine, 2)[0])
+ switch attribute {
+ // The @summary, @router, @success, @failure annotation belongs to Operation
+ case summaryAttr, routerAttr, successAttr, failureAttr, responseAttr:
+ return false
+ }
+ }
+
+ return true
+}
+
+func getMarkdownForTag(tagName string, dirPath string) ([]byte, error) {
+ dirEntries, err := os.ReadDir(dirPath)
+ if err != nil {
+ return nil, err
+ }
+
+ for _, entry := range dirEntries {
+ if entry.IsDir() {
+ continue
+ }
+
+ fileName := entry.Name()
+
+ if !strings.Contains(fileName, ".md") {
+ continue
+ }
+
+ if strings.Contains(fileName, tagName) {
+ fullPath := filepath.Join(dirPath, fileName)
+
+ commentInfo, err := os.ReadFile(fullPath)
+ if err != nil {
+ return nil, fmt.Errorf("Failed to read markdown file %s error: %s ", fullPath, err)
+ }
+
+ return commentInfo, nil
+ }
+ }
+
+ return nil, fmt.Errorf("Unable to find markdown file for tag %s in the given directory", tagName)
+}
+
+func isExistsScope(scope string) (bool, error) {
+ s := strings.Fields(scope)
+ for _, v := range s {
+ if strings.HasPrefix(v, scopeAttrPrefix) {
+ if strings.Contains(v, ",") {
+ return false, fmt.Errorf("@scope can't use comma(,) get=" + v)
+ }
+ }
+ }
+
+ return strings.HasPrefix(scope, scopeAttrPrefix), nil
+}
+
+func getTagsFromComment(comment string) (tags []string) {
+ commentLine := strings.TrimSpace(strings.TrimLeft(comment, "/"))
+ if len(commentLine) == 0 {
+ return nil
+ }
+
+ attribute := strings.Fields(commentLine)[0]
+ lineRemainder, lowerAttribute := strings.TrimSpace(commentLine[len(attribute):]), strings.ToLower(attribute)
+
+ if lowerAttribute == tagsAttr {
+ for _, tag := range strings.Split(lineRemainder, ",") {
+ tags = append(tags, strings.TrimSpace(tag))
+ }
+ }
+ return
+
+}
+
+func (parser *Parser) matchTags(comments []*ast.Comment) (match bool) {
+ if len(parser.tags) == 0 {
+ return true
+ }
+
+ match = false
+ for _, comment := range comments {
+ for _, tag := range getTagsFromComment(comment.Text) {
+ if _, has := parser.tags["!"+tag]; has {
+ return false
+ }
+ if _, has := parser.tags[tag]; has {
+ match = true // keep iterating as it may contain a tag that is excluded
+ }
+ }
+ }
+
+ if !match {
+ // If all tags are negation then we should return true
+ for key := range parser.tags {
+ if key[0] != '!' {
+ return false
+ }
+ }
+ }
+ return true
+}
+
+func matchExtension(extensionToMatch string, comments []*ast.Comment) (match bool) {
+ if len(extensionToMatch) != 0 {
+ for _, comment := range comments {
+ commentLine := strings.TrimSpace(strings.TrimLeft(comment.Text, "/"))
+ fields := FieldsByAnySpace(commentLine, 2)
+ if len(fields) > 0 {
+ lowerAttribute := strings.ToLower(fields[0])
+
+ if lowerAttribute == fmt.Sprintf("@x-%s", strings.ToLower(extensionToMatch)) {
+ return true
+ }
+ }
+ }
+ return false
+ }
+ return true
+}
+
+// ParseRouterAPIInfo parses router api info for given astFile.
+func (parser *Parser) ParseRouterAPIInfo(fileInfo *AstFileInfo) error {
+DeclsLoop:
+ for _, astDescription := range fileInfo.File.Decls {
+ if (fileInfo.ParseFlag & ParseOperations) == ParseNone {
+ continue
+ }
+ astDeclaration, ok := astDescription.(*ast.FuncDecl)
+ if ok && astDeclaration.Doc != nil && astDeclaration.Doc.List != nil {
+ if parser.matchTags(astDeclaration.Doc.List) &&
+ matchExtension(parser.parseExtension, astDeclaration.Doc.List) {
+ // for per 'function' comment, create a new 'Operation' object
+ operation := NewOperation(parser, SetCodeExampleFilesDirectory(parser.codeExampleFilesDir))
+ for _, comment := range astDeclaration.Doc.List {
+ err := operation.ParseComment(comment.Text, fileInfo.File)
+ if err != nil {
+ return fmt.Errorf("ParseComment error in file %s :%+v", fileInfo.Path, err)
+ }
+ if operation.State != "" && operation.State != parser.HostState {
+ continue DeclsLoop
+ }
+ }
+ err := processRouterOperation(parser, operation)
+ if err != nil {
+ return err
+ }
+ }
+ }
+ }
+
+ return nil
+}
+
+func refRouteMethodOp(item *spec.PathItem, method string) (op **spec.Operation) {
+ switch method {
+ case http.MethodGet:
+ op = &item.Get
+ case http.MethodPost:
+ op = &item.Post
+ case http.MethodDelete:
+ op = &item.Delete
+ case http.MethodPut:
+ op = &item.Put
+ case http.MethodPatch:
+ op = &item.Patch
+ case http.MethodHead:
+ op = &item.Head
+ case http.MethodOptions:
+ op = &item.Options
+ }
+
+ return
+}
+
+func processRouterOperation(parser *Parser, operation *Operation) error {
+ for _, routeProperties := range operation.RouterProperties {
+ var (
+ pathItem spec.PathItem
+ ok bool
+ )
+
+ pathItem, ok = parser.swagger.Paths.Paths[routeProperties.Path]
+ if !ok {
+ pathItem = spec.PathItem{}
+ }
+
+ op := refRouteMethodOp(&pathItem, routeProperties.HTTPMethod)
+
+ // check if we already have an operation for this path and method
+ if *op != nil {
+ err := fmt.Errorf("route %s %s is declared multiple times", routeProperties.HTTPMethod, routeProperties.Path)
+ if parser.Strict {
+ return err
+ }
+
+ parser.debug.Printf("warning: %s\n", err)
+ }
+
+ if len(operation.RouterProperties) > 1 {
+ newOp := *operation
+ var validParams []spec.Parameter
+ for _, param := range newOp.Operation.OperationProps.Parameters {
+ if param.In == "path" && !strings.Contains(routeProperties.Path, param.Name) {
+ // This path param is not actually contained in the path, skip adding it to the final params
+ continue
+ }
+ validParams = append(validParams, param)
+ }
+ newOp.Operation.OperationProps.Parameters = validParams
+ *op = &newOp.Operation
+ } else {
+ *op = &operation.Operation
+ }
+
+ if routeProperties.Deprecated {
+ (*op).Deprecated = routeProperties.Deprecated
+ }
+
+ parser.swagger.Paths.Paths[routeProperties.Path] = pathItem
+ }
+
+ return nil
+}
+
+func convertFromSpecificToPrimitive(typeName string) (string, error) {
+ name := typeName
+ if strings.ContainsRune(name, '.') {
+ name = strings.Split(name, ".")[1]
+ }
+
+ switch strings.ToUpper(name) {
+ case "TIME", "OBJECTID", "UUID":
+ return STRING, nil
+ case "DECIMAL":
+ return NUMBER, nil
+ }
+
+ return typeName, ErrFailedConvertPrimitiveType
+}
+
+func (parser *Parser) getTypeSchema(typeName string, file *ast.File, ref bool) (*spec.Schema, error) {
+ if override, ok := parser.Overrides[typeName]; ok {
+ parser.debug.Printf("Override detected for %s: using %s instead", typeName, override)
+ return parseObjectSchema(parser, override, file)
+ }
+
+ if IsInterfaceLike(typeName) {
+ return &spec.Schema{}, nil
+ }
+ if IsGolangPrimitiveType(typeName) {
+ return PrimitiveSchema(TransToValidSchemeType(typeName)), nil
+ }
+
+ schemaType, err := convertFromSpecificToPrimitive(typeName)
+ if err == nil {
+ return PrimitiveSchema(schemaType), nil
+ }
+
+ typeSpecDef := parser.packages.FindTypeSpec(typeName, file)
+ if typeSpecDef == nil {
+ return nil, fmt.Errorf("cannot find type definition: %s", typeName)
+ }
+
+ if override, ok := parser.Overrides[typeSpecDef.FullPath()]; ok {
+ if override == "" {
+ parser.debug.Printf("Override detected for %s: ignoring", typeSpecDef.FullPath())
+
+ return nil, ErrSkippedField
+ }
+
+ parser.debug.Printf("Override detected for %s: using %s instead", typeSpecDef.FullPath(), override)
+
+ separator := strings.LastIndex(override, ".")
+ if separator == -1 {
+ // treat as a swaggertype tag
+ parts := strings.Split(override, ",")
+
+ return BuildCustomSchema(parts)
+ }
+
+ typeSpecDef = parser.packages.findTypeSpec(override[0:separator], override[separator+1:])
+ }
+
+ schema, ok := parser.parsedSchemas[typeSpecDef]
+ if !ok {
+ var err error
+
+ schema, err = parser.ParseDefinition(typeSpecDef)
+ if err != nil {
+ if err == ErrRecursiveParseStruct && ref {
+ return parser.getRefTypeSchema(typeSpecDef, schema), nil
+ }
+ return nil, fmt.Errorf("%s: %w", typeName, err)
+ }
+ }
+
+ if ref {
+ if IsComplexSchema(schema.Schema) {
+ return parser.getRefTypeSchema(typeSpecDef, schema), nil
+ }
+ // if it is a simple schema, just return a copy
+ newSchema := *schema.Schema
+ return &newSchema, nil
+ }
+
+ return schema.Schema, nil
+}
+
+func (parser *Parser) getRefTypeSchema(typeSpecDef *TypeSpecDef, schema *Schema) *spec.Schema {
+ _, ok := parser.outputSchemas[typeSpecDef]
+ if !ok {
+ parser.swagger.Definitions[schema.Name] = spec.Schema{}
+
+ if schema.Schema != nil {
+ parser.swagger.Definitions[schema.Name] = *schema.Schema
+ }
+
+ parser.outputSchemas[typeSpecDef] = schema
+ }
+
+ refSchema := RefSchema(schema.Name)
+
+ return refSchema
+}
+
+func (parser *Parser) isInStructStack(typeSpecDef *TypeSpecDef) bool {
+ for _, specDef := range parser.structStack {
+ if typeSpecDef == specDef {
+ return true
+ }
+ }
+
+ return false
+}
+
+// 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 *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error) {
+ typeName := typeSpecDef.TypeName()
+ schema, found := parser.parsedSchemas[typeSpecDef]
+ if found {
+ parser.debug.Printf("Skipping '%s', already parsed.", typeName)
+
+ return schema, nil
+ }
+
+ if parser.isInStructStack(typeSpecDef) {
+ parser.debug.Printf("Skipping '%s', recursion detected.", typeName)
+
+ return &Schema{
+ Name: typeName,
+ PkgPath: typeSpecDef.PkgPath,
+ Schema: PrimitiveSchema(OBJECT),
+ },
+ ErrRecursiveParseStruct
+ }
+
+ parser.structStack = append(parser.structStack, typeSpecDef)
+
+ parser.debug.Printf("Generating %s", typeName)
+
+ definition, err := parser.parseTypeExpr(typeSpecDef.File, typeSpecDef.TypeSpec.Type, false)
+ if err != nil {
+ parser.debug.Printf("Error parsing type definition '%s': %s", typeName, err)
+ return nil, err
+ }
+
+ if definition.Description == "" {
+ fillDefinitionDescription(definition, typeSpecDef.File, typeSpecDef)
+ }
+
+ if len(typeSpecDef.Enums) > 0 {
+ var varnames []string
+ var enumComments = make(map[string]string)
+ for _, value := range typeSpecDef.Enums {
+ definition.Enum = append(definition.Enum, value.Value)
+ varnames = append(varnames, value.key)
+ if len(value.Comment) > 0 {
+ enumComments[value.key] = value.Comment
+ }
+ }
+ if definition.Extensions == nil {
+ definition.Extensions = make(spec.Extensions)
+ }
+ definition.Extensions[enumVarNamesExtension] = varnames
+ if len(enumComments) > 0 {
+ definition.Extensions[enumCommentsExtension] = enumComments
+ }
+ }
+
+ sch := Schema{
+ Name: typeName,
+ PkgPath: typeSpecDef.PkgPath,
+ Schema: definition,
+ }
+ parser.parsedSchemas[typeSpecDef] = &sch
+
+ // update an empty schema as a result of recursion
+ s2, found := parser.outputSchemas[typeSpecDef]
+ if found {
+ parser.swagger.Definitions[s2.Name] = *definition
+ }
+
+ return &sch, nil
+}
+
+func fullTypeName(parts ...string) string {
+ return strings.Join(parts, ".")
+}
+
+// fillDefinitionDescription additionally fills fields in definition (spec.Schema)
+// TODO: If .go file contains many types, it may work for a long time
+func fillDefinitionDescription(definition *spec.Schema, file *ast.File, typeSpecDef *TypeSpecDef) {
+ if file == nil {
+ return
+ }
+ for _, astDeclaration := range file.Decls {
+ generalDeclaration, ok := astDeclaration.(*ast.GenDecl)
+ if !ok || generalDeclaration.Tok != token.TYPE {
+ continue
+ }
+
+ for _, astSpec := range generalDeclaration.Specs {
+ typeSpec, ok := astSpec.(*ast.TypeSpec)
+ if !ok || typeSpec != typeSpecDef.TypeSpec {
+ continue
+ }
+
+ definition.Description =
+ extractDeclarationDescription(typeSpec.Doc, typeSpec.Comment, generalDeclaration.Doc)
+ }
+ }
+}
+
+// extractDeclarationDescription gets first description
+// from attribute descriptionAttr in commentGroups (ast.CommentGroup)
+func extractDeclarationDescription(commentGroups ...*ast.CommentGroup) string {
+ var description string
+
+ for _, commentGroup := range commentGroups {
+ if commentGroup == nil {
+ continue
+ }
+
+ isHandlingDescription := false
+
+ for _, comment := range commentGroup.List {
+ commentText := strings.TrimSpace(strings.TrimLeft(comment.Text, "/"))
+ if len(commentText) == 0 {
+ continue
+ }
+ attribute := FieldsByAnySpace(commentText, 2)[0]
+
+ if strings.ToLower(attribute) != descriptionAttr {
+ if !isHandlingDescription {
+ continue
+ }
+
+ break
+ }
+
+ isHandlingDescription = true
+ description += " " + strings.TrimSpace(commentText[len(attribute):])
+ }
+ }
+
+ return strings.TrimLeft(description, " ")
+}
+
+// parseTypeExpr parses given type expression that corresponds to the type under
+// given name and package, and returns swagger schema for it.
+func (parser *Parser) parseTypeExpr(file *ast.File, typeExpr ast.Expr, ref bool) (*spec.Schema, error) {
+ switch expr := typeExpr.(type) {
+ // type Foo interface{}
+ case *ast.InterfaceType:
+ return &spec.Schema{}, nil
+
+ // type Foo struct {...}
+ case *ast.StructType:
+ return parser.parseStruct(file, expr.Fields)
+
+ // type Foo Baz
+ case *ast.Ident:
+ return parser.getTypeSchema(expr.Name, file, ref)
+
+ // type Foo *Baz
+ case *ast.StarExpr:
+ return parser.parseTypeExpr(file, expr.X, ref)
+
+ // type Foo pkg.Bar
+ case *ast.SelectorExpr:
+ if xIdent, ok := expr.X.(*ast.Ident); ok {
+ return parser.getTypeSchema(fullTypeName(xIdent.Name, expr.Sel.Name), file, ref)
+ }
+ // type Foo []Baz
+ case *ast.ArrayType:
+ itemSchema, err := parser.parseTypeExpr(file, expr.Elt, true)
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.ArrayProperty(itemSchema), nil
+ // type Foo map[string]Bar
+ case *ast.MapType:
+ if _, ok := expr.Value.(*ast.InterfaceType); ok {
+ return spec.MapProperty(nil), nil
+ }
+ schema, err := parser.parseTypeExpr(file, expr.Value, true)
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.MapProperty(schema), nil
+
+ case *ast.FuncType:
+ return nil, ErrFuncTypeField
+ // ...
+ }
+
+ return parser.parseGenericTypeExpr(file, typeExpr)
+}
+
+func (parser *Parser) parseStruct(file *ast.File, fields *ast.FieldList) (*spec.Schema, error) {
+ required, properties := make([]string, 0), make(map[string]spec.Schema)
+
+ for _, field := range fields.List {
+ fieldProps, requiredFromAnon, err := parser.parseStructField(file, field)
+ if err != nil {
+ if errors.Is(err, ErrFuncTypeField) || errors.Is(err, ErrSkippedField) {
+ continue
+ }
+
+ return nil, err
+ }
+
+ if len(fieldProps) == 0 {
+ continue
+ }
+
+ required = append(required, requiredFromAnon...)
+
+ for k, v := range fieldProps {
+ properties[k] = v
+ }
+ }
+
+ sort.Strings(required)
+
+ return &spec.Schema{
+ SchemaProps: spec.SchemaProps{
+ Type: []string{OBJECT},
+ Properties: properties,
+ Required: required,
+ },
+ }, nil
+}
+
+func (parser *Parser) parseStructField(file *ast.File, field *ast.Field) (map[string]spec.Schema, []string, error) {
+ if field.Tag != nil {
+ skip, ok := reflect.StructTag(strings.ReplaceAll(field.Tag.Value, "`", "")).Lookup("swaggerignore")
+ if ok && strings.EqualFold(skip, "true") {
+ return nil, nil, nil
+ }
+ }
+
+ ps := parser.fieldParserFactory(parser, field)
+
+ if ps.ShouldSkip() {
+ return nil, nil, nil
+ }
+
+ fieldName, err := ps.FieldName()
+ if err != nil {
+ return nil, nil, err
+ }
+
+ if fieldName == "" {
+ typeName, err := getFieldType(file, field.Type, nil)
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+
+ schema, err := parser.getTypeSchema(typeName, file, false)
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+
+ if len(schema.Type) > 0 && schema.Type[0] == OBJECT {
+ if len(schema.Properties) == 0 {
+ return nil, nil, nil
+ }
+
+ properties := map[string]spec.Schema{}
+ for k, v := range schema.Properties {
+ properties[k] = v
+ }
+
+ return properties, schema.SchemaProps.Required, nil
+ }
+ // for alias type of non-struct types ,such as array,map, etc. ignore field tag.
+ return map[string]spec.Schema{typeName: *schema}, nil, nil
+
+ }
+
+ schema, err := ps.CustomSchema()
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+
+ if schema == nil {
+ typeName, err := getFieldType(file, field.Type, nil)
+ if err == nil {
+ // named type
+ schema, err = parser.getTypeSchema(typeName, file, true)
+ } else {
+ // unnamed type
+ schema, err = parser.parseTypeExpr(file, field.Type, false)
+ }
+
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+ }
+
+ err = ps.ComplementSchema(schema)
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+
+ var tagRequired []string
+
+ required, err := ps.IsRequired()
+ if err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", fieldName, err)
+ }
+
+ if required {
+ tagRequired = append(tagRequired, fieldName)
+ }
+
+ if schema.Extensions == nil {
+ schema.Extensions = make(spec.Extensions)
+ }
+ if formName := ps.FormName(); len(formName) > 0 {
+ schema.Extensions["formData"] = formName
+ }
+ if headerName := ps.HeaderName(); len(headerName) > 0 {
+ schema.Extensions["header"] = headerName
+ }
+ if pathName := ps.PathName(); len(pathName) > 0 {
+ schema.Extensions["path"] = pathName
+ }
+
+ return map[string]spec.Schema{fieldName: *schema}, tagRequired, nil
+}
+
+func getFieldType(file *ast.File, field ast.Expr, genericParamTypeDefs map[string]*genericTypeSpec) (string, error) {
+ switch fieldType := field.(type) {
+ case *ast.Ident:
+ return fieldType.Name, nil
+ case *ast.SelectorExpr:
+ packageName, err := getFieldType(file, fieldType.X, genericParamTypeDefs)
+ if err != nil {
+ return "", err
+ }
+
+ return fullTypeName(packageName, fieldType.Sel.Name), nil
+ case *ast.StarExpr:
+ fullName, err := getFieldType(file, fieldType.X, genericParamTypeDefs)
+ if err != nil {
+ return "", err
+ }
+
+ return fullName, nil
+ default:
+ return getGenericFieldType(file, field, genericParamTypeDefs)
+ }
+}
+
+func (parser *Parser) getUnderlyingSchema(schema *spec.Schema) *spec.Schema {
+ if schema == nil {
+ return nil
+ }
+
+ if url := schema.Ref.GetURL(); url != nil {
+ if pos := strings.LastIndexByte(url.Fragment, '/'); pos >= 0 {
+ name := url.Fragment[pos+1:]
+ if schema, ok := parser.swagger.Definitions[name]; ok {
+ return &schema
+ }
+ }
+ }
+
+ if len(schema.AllOf) > 0 {
+ merged := &spec.Schema{}
+ MergeSchema(merged, schema)
+ for _, s := range schema.AllOf {
+ MergeSchema(merged, parser.getUnderlyingSchema(&s))
+ }
+ return merged
+ }
+ return nil
+}
+
+// GetSchemaTypePath get path of schema type.
+func (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string {
+ if schema == nil || depth == 0 {
+ return nil
+ }
+
+ if underlying := parser.getUnderlyingSchema(schema); underlying != nil {
+ return parser.GetSchemaTypePath(underlying, depth)
+ }
+
+ if len(schema.Type) > 0 {
+ switch schema.Type[0] {
+ case ARRAY:
+ depth--
+
+ s := []string{schema.Type[0]}
+
+ return append(s, parser.GetSchemaTypePath(schema.Items.Schema, depth)...)
+ case OBJECT:
+ if schema.AdditionalProperties != nil && schema.AdditionalProperties.Schema != nil {
+ // for map
+ depth--
+
+ s := []string{schema.Type[0]}
+
+ return append(s, parser.GetSchemaTypePath(schema.AdditionalProperties.Schema, depth)...)
+ }
+ }
+
+ return []string{schema.Type[0]}
+ }
+
+ return []string{ANY}
+}
+
+func replaceLastTag(slice []spec.Tag, element spec.Tag) {
+ slice = append(slice[:len(slice)-1], element)
+}
+
+// defineTypeOfExample example value define the type (object and array unsupported).
+func defineTypeOfExample(schemaType, arrayType, exampleValue string) (interface{}, error) {
+ switch schemaType {
+ case STRING:
+ return exampleValue, nil
+ case NUMBER:
+ v, err := strconv.ParseFloat(exampleValue, 64)
+ if err != nil {
+ return nil, fmt.Errorf("example value %s can't convert to %s err: %s", exampleValue, schemaType, err)
+ }
+
+ return v, nil
+ case INTEGER:
+ v, err := strconv.Atoi(exampleValue)
+ if err != nil {
+ return nil, fmt.Errorf("example value %s can't convert to %s err: %s", exampleValue, schemaType, err)
+ }
+
+ return v, nil
+ case BOOLEAN:
+ v, err := strconv.ParseBool(exampleValue)
+ if err != nil {
+ return nil, fmt.Errorf("example value %s can't convert to %s err: %s", exampleValue, schemaType, err)
+ }
+
+ return v, nil
+ case ARRAY:
+ values := strings.Split(exampleValue, ",")
+ result := make([]interface{}, 0)
+ for _, value := range values {
+ v, err := defineTypeOfExample(arrayType, "", value)
+ if err != nil {
+ return nil, err
+ }
+
+ result = append(result, v)
+ }
+
+ return result, nil
+ case OBJECT:
+ if arrayType == "" {
+ return nil, fmt.Errorf("%s is unsupported type in example value `%s`", schemaType, exampleValue)
+ }
+
+ values := strings.Split(exampleValue, ",")
+
+ result := map[string]interface{}{}
+
+ for _, value := range values {
+ mapData := strings.SplitN(value, ":", 2)
+
+ if len(mapData) == 2 {
+ v, err := defineTypeOfExample(arrayType, "", mapData[1])
+ if err != nil {
+ return nil, err
+ }
+
+ result[mapData[0]] = v
+
+ continue
+ }
+
+ return nil, fmt.Errorf("example value %s should format: key:value", exampleValue)
+ }
+
+ return result, nil
+ }
+
+ return nil, fmt.Errorf("%s is unsupported type in example value %s", schemaType, exampleValue)
+}
+
+// GetAllGoFileInfo gets all Go source files information for given searchDir.
+func (parser *Parser) getAllGoFileInfo(packageDir, searchDir string) error {
+ if parser.skipPackageByPrefix(packageDir) {
+ return nil // ignored by user-defined package path prefixes
+ }
+ return filepath.Walk(searchDir, func(path string, f os.FileInfo, _ error) error {
+ err := parser.Skip(path, f)
+ if err != nil {
+ return err
+ }
+
+ if f.IsDir() {
+ return nil
+ }
+
+ relPath, err := filepath.Rel(searchDir, path)
+ if err != nil {
+ return err
+ }
+
+ return parser.parseFile(filepath.ToSlash(filepath.Dir(filepath.Clean(filepath.Join(packageDir, relPath)))), path, nil, ParseAll)
+ })
+}
+
+func (parser *Parser) getAllGoFileInfoFromDeps(pkg *depth.Pkg, parseFlag ParseFlag) error {
+ ignoreInternal := pkg.Internal && !parser.ParseInternal
+ if ignoreInternal || !pkg.Resolved { // ignored internal and not resolved dependencies
+ return nil
+ }
+
+ if pkg.Raw != nil && parser.skipPackageByPrefix(pkg.Raw.ImportPath) {
+ return nil // ignored by user-defined package path prefixes
+ }
+
+ // Skip cgo
+ if pkg.Raw == nil && pkg.Name == "C" {
+ return nil
+ }
+
+ srcDir := pkg.Raw.Dir
+
+ files, err := os.ReadDir(srcDir) // only parsing files in the dir(don't contain sub dir files)
+ if err != nil {
+ return err
+ }
+
+ for _, f := range files {
+ if f.IsDir() {
+ continue
+ }
+
+ path := filepath.Join(srcDir, f.Name())
+ if err := parser.parseFile(pkg.Name, path, nil, parseFlag); err != nil {
+ return err
+ }
+ }
+
+ for i := 0; i < len(pkg.Deps); i++ {
+ if err := parser.getAllGoFileInfoFromDeps(&pkg.Deps[i], parseFlag); err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+func (parser *Parser) parseFile(packageDir, path string, src interface{}, flag ParseFlag) error {
+ if strings.HasSuffix(strings.ToLower(path), "_test.go") || filepath.Ext(path) != ".go" {
+ return nil
+ }
+
+ return parser.packages.ParseFile(packageDir, path, src, flag)
+}
+
+func (parser *Parser) checkOperationIDUniqueness() error {
+ // operationsIds contains all operationId annotations to check it's unique
+ operationsIds := make(map[string]string)
+
+ for path, item := range parser.swagger.Paths.Paths {
+ var method, id string
+
+ for method = range allMethod {
+ op := refRouteMethodOp(&item, method)
+ if *op != nil {
+ id = (**op).ID
+
+ break
+ }
+ }
+
+ if id == "" {
+ continue
+ }
+
+ current := fmt.Sprintf("%s %s", method, path)
+
+ previous, ok := operationsIds[id]
+ if ok {
+ return fmt.Errorf(
+ "duplicated @id annotation '%s' found in '%s', previously declared in: '%s'",
+ id, current, previous)
+ }
+
+ operationsIds[id] = current
+ }
+
+ return nil
+}
+
+// Skip returns filepath.SkipDir error if match vendor and hidden folder.
+func (parser *Parser) Skip(path string, f os.FileInfo) error {
+ return walkWith(parser.excludes, parser.ParseVendor)(path, f)
+}
+
+func walkWith(excludes map[string]struct{}, parseVendor bool) func(path string, fileInfo os.FileInfo) error {
+ return func(path string, f os.FileInfo) error {
+ if f.IsDir() {
+ if !parseVendor && f.Name() == "vendor" || // ignore "vendor"
+ f.Name() == "docs" || // exclude docs
+ len(f.Name()) > 1 && f.Name()[0] == '.' && f.Name() != ".." { // exclude all hidden folder
+ return filepath.SkipDir
+ }
+
+ if excludes != nil {
+ if _, ok := excludes[path]; ok {
+ return filepath.SkipDir
+ }
+ }
+ }
+
+ return nil
+ }
+}
+
+// GetSwagger returns *spec.Swagger which is the root document object for the API specification.
+func (parser *Parser) GetSwagger() *spec.Swagger {
+ return parser.swagger
+}
+
+// addTestType just for tests.
+func (parser *Parser) addTestType(typename string) {
+ typeDef := &TypeSpecDef{}
+ parser.packages.uniqueDefinitions[typename] = typeDef
+ parser.parsedSchemas[typeDef] = &Schema{
+ PkgPath: "",
+ Name: typename,
+ Schema: PrimitiveSchema(OBJECT),
+ }
+}
diff --git a/vendor/github.com/swaggo/swag/schema.go b/vendor/github.com/swaggo/swag/schema.go
new file mode 100644
index 0000000..b3a5b38
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/schema.go
@@ -0,0 +1,293 @@
+package swag
+
+import (
+ "errors"
+ "fmt"
+ "github.com/go-openapi/spec"
+)
+
+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 = '$'
+)
+
+// CheckSchemaType checks if typeName is not a name of primitive type.
+func CheckSchemaType(typeName string) error {
+ if !IsPrimitiveType(typeName) {
+ return fmt.Errorf("%s is not basic types", typeName)
+ }
+
+ return nil
+}
+
+// IsSimplePrimitiveType determine whether the type name is a simple primitive type.
+func IsSimplePrimitiveType(typeName string) bool {
+ switch typeName {
+ case STRING, NUMBER, INTEGER, BOOLEAN:
+ return true
+ }
+
+ return false
+}
+
+// IsPrimitiveType determine whether the type name is a primitive type.
+func IsPrimitiveType(typeName string) bool {
+ switch typeName {
+ case STRING, NUMBER, INTEGER, BOOLEAN, ARRAY, OBJECT, FUNC:
+ return true
+ }
+
+ return false
+}
+
+// IsInterfaceLike determines whether the swagger type name is an go named interface type like error type.
+func IsInterfaceLike(typeName string) bool {
+ return typeName == ERROR || typeName == ANY
+}
+
+// IsNumericType determines whether the swagger type name is a numeric type.
+func IsNumericType(typeName string) bool {
+ return typeName == INTEGER || typeName == NUMBER
+}
+
+// TransToValidSchemeType indicates type will transfer golang basic type to swagger supported type.
+func TransToValidSchemeType(typeName string) string {
+ switch typeName {
+ case "uint", "int", "uint8", "int8", "uint16", "int16", "byte":
+ return INTEGER
+ case "uint32", "int32", "rune":
+ return INTEGER
+ case "uint64", "int64":
+ return INTEGER
+ case "float32", "float64":
+ return NUMBER
+ case "bool":
+ return BOOLEAN
+ case "string":
+ return STRING
+ }
+
+ return typeName
+}
+
+// IsGolangPrimitiveType determine whether the type name is a golang primitive type.
+func IsGolangPrimitiveType(typeName string) bool {
+ switch typeName {
+ case "uint",
+ "int",
+ "uint8",
+ "int8",
+ "uint16",
+ "int16",
+ "byte",
+ "uint32",
+ "int32",
+ "rune",
+ "uint64",
+ "int64",
+ "float32",
+ "float64",
+ "bool",
+ "string":
+ return true
+ }
+
+ return false
+}
+
+// TransToValidCollectionFormat determine valid collection format.
+func TransToValidCollectionFormat(format string) string {
+ switch format {
+ case "csv", "multi", "pipes", "tsv", "ssv":
+ return format
+ }
+
+ return ""
+}
+
+func ignoreNameOverride(name string) bool {
+ return len(name) != 0 && name[0] == IgnoreNameOverridePrefix
+}
+
+// IsComplexSchema whether a schema is complex and should be a ref schema
+func IsComplexSchema(schema *spec.Schema) bool {
+ // a enum type should be complex
+ if len(schema.Enum) > 0 {
+ return true
+ }
+
+ // a deep array type is complex, how to determine deep? here more than 2 ,for example: [][]object,[][][]int
+ if len(schema.Type) > 2 {
+ return true
+ }
+
+ //Object included, such as Object or []Object
+ for _, st := range schema.Type {
+ if st == OBJECT {
+ return true
+ }
+ }
+ return false
+}
+
+// IsRefSchema whether a schema is a reference schema.
+func IsRefSchema(schema *spec.Schema) bool {
+ return schema.Ref.Ref.GetURL() != nil
+}
+
+// RefSchema build a reference schema.
+func RefSchema(refType string) *spec.Schema {
+ return spec.RefSchema("#/definitions/" + refType)
+}
+
+// PrimitiveSchema build a primitive schema.
+func PrimitiveSchema(refType string) *spec.Schema {
+ return &spec.Schema{SchemaProps: spec.SchemaProps{Type: []string{refType}}}
+}
+
+// BuildCustomSchema build custom schema specified by tag swaggertype.
+func BuildCustomSchema(types []string) (*spec.Schema, error) {
+ if len(types) == 0 {
+ return nil, nil
+ }
+
+ switch types[0] {
+ case PRIMITIVE:
+ if len(types) == 1 {
+ return nil, errors.New("need primitive type after primitive")
+ }
+
+ return BuildCustomSchema(types[1:])
+ case ARRAY:
+ if len(types) == 1 {
+ return nil, errors.New("need array item type after array")
+ }
+
+ schema, err := BuildCustomSchema(types[1:])
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.ArrayProperty(schema), nil
+ case OBJECT:
+ if len(types) == 1 {
+ return PrimitiveSchema(types[0]), nil
+ }
+
+ schema, err := BuildCustomSchema(types[1:])
+ if err != nil {
+ return nil, err
+ }
+
+ return spec.MapProperty(schema), nil
+ default:
+ err := CheckSchemaType(types[0])
+ if err != nil {
+ return nil, err
+ }
+
+ return PrimitiveSchema(types[0]), nil
+ }
+}
+
+// MergeSchema merge schemas
+func MergeSchema(dst *spec.Schema, src *spec.Schema) *spec.Schema {
+ if len(src.Type) > 0 {
+ dst.Type = src.Type
+ }
+ if len(src.Properties) > 0 {
+ dst.Properties = src.Properties
+ }
+ if src.Items != nil {
+ dst.Items = src.Items
+ }
+ if src.AdditionalProperties != nil {
+ dst.AdditionalProperties = src.AdditionalProperties
+ }
+ if len(src.Description) > 0 {
+ dst.Description = src.Description
+ }
+ if src.Nullable {
+ dst.Nullable = src.Nullable
+ }
+ if len(src.Format) > 0 {
+ dst.Format = src.Format
+ }
+ if src.Default != nil {
+ dst.Default = src.Default
+ }
+ if src.Example != nil {
+ dst.Example = src.Example
+ }
+ if len(src.Extensions) > 0 {
+ dst.Extensions = src.Extensions
+ }
+ if src.Maximum != nil {
+ dst.Maximum = src.Maximum
+ }
+ if src.Minimum != nil {
+ dst.Minimum = src.Minimum
+ }
+ if src.ExclusiveMaximum {
+ dst.ExclusiveMaximum = src.ExclusiveMaximum
+ }
+ if src.ExclusiveMinimum {
+ dst.ExclusiveMinimum = src.ExclusiveMinimum
+ }
+ if src.MaxLength != nil {
+ dst.MaxLength = src.MaxLength
+ }
+ if src.MinLength != nil {
+ dst.MinLength = src.MinLength
+ }
+ if len(src.Pattern) > 0 {
+ dst.Pattern = src.Pattern
+ }
+ if src.MaxItems != nil {
+ dst.MaxItems = src.MaxItems
+ }
+ if src.MinItems != nil {
+ dst.MinItems = src.MinItems
+ }
+ if src.UniqueItems {
+ dst.UniqueItems = src.UniqueItems
+ }
+ if src.MultipleOf != nil {
+ dst.MultipleOf = src.MultipleOf
+ }
+ if len(src.Enum) > 0 {
+ dst.Enum = src.Enum
+ }
+ if len(src.Extensions) > 0 {
+ dst.Extensions = src.Extensions
+ }
+ if len(src.ExtraProps) > 0 {
+ dst.ExtraProps = src.ExtraProps
+ }
+ return dst
+}
diff --git a/vendor/github.com/swaggo/swag/spec.go b/vendor/github.com/swaggo/swag/spec.go
new file mode 100644
index 0000000..c18a365
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/spec.go
@@ -0,0 +1,64 @@
+package swag
+
+import (
+ "bytes"
+ "encoding/json"
+ "strings"
+ "text/template"
+)
+
+// Spec holds exported Swagger Info so clients can modify it.
+type Spec struct {
+ Version string
+ Host string
+ BasePath string
+ Schemes []string
+ Title string
+ Description string
+ InfoInstanceName string
+ SwaggerTemplate string
+ LeftDelim string
+ RightDelim string
+}
+
+// ReadDoc parses SwaggerTemplate into swagger document.
+func (i *Spec) ReadDoc() string {
+ i.Description = strings.ReplaceAll(i.Description, "\n", "\\n")
+
+ tpl := template.New("swagger_info").Funcs(template.FuncMap{
+ "marshal": func(v interface{}) string {
+ a, _ := json.Marshal(v)
+
+ return string(a)
+ },
+ "escape": func(v interface{}) string {
+ // escape tabs
+ var str = strings.ReplaceAll(v.(string), "\t", "\\t")
+ // replace " with \", and if that results in \\", replace that with \\\"
+ str = strings.ReplaceAll(str, "\"", "\\\"")
+
+ return strings.ReplaceAll(str, "\\\\\"", "\\\\\\\"")
+ },
+ })
+
+ if i.LeftDelim != "" && i.RightDelim != "" {
+ tpl = tpl.Delims(i.LeftDelim, i.RightDelim)
+ }
+
+ parsed, err := tpl.Parse(i.SwaggerTemplate)
+ if err != nil {
+ return i.SwaggerTemplate
+ }
+
+ var doc bytes.Buffer
+ if err = parsed.Execute(&doc, i); err != nil {
+ return i.SwaggerTemplate
+ }
+
+ return doc.String()
+}
+
+// InstanceName returns Spec instance name.
+func (i *Spec) InstanceName() string {
+ return i.InfoInstanceName
+}
diff --git a/vendor/github.com/swaggo/swag/swagger.go b/vendor/github.com/swaggo/swag/swagger.go
new file mode 100644
index 0000000..74c162c
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/swagger.go
@@ -0,0 +1,72 @@
+package swag
+
+import (
+ "errors"
+ "fmt"
+ "sync"
+)
+
+// Name is a unique name be used to register swag instance.
+const Name = "swagger"
+
+var (
+ swaggerMu sync.RWMutex
+ swags map[string]Swagger
+)
+
+// Swagger is an interface to read swagger document.
+type Swagger interface {
+ ReadDoc() string
+}
+
+// Register registers swagger for given name.
+func Register(name string, swagger Swagger) {
+ swaggerMu.Lock()
+ defer swaggerMu.Unlock()
+
+ if swagger == nil {
+ panic("swagger is nil")
+ }
+
+ if swags == nil {
+ swags = make(map[string]Swagger)
+ }
+
+ if _, ok := swags[name]; ok {
+ panic("Register called twice for swag: " + name)
+ }
+
+ swags[name] = swagger
+}
+
+// GetSwagger returns the swagger instance for given name.
+// If not found, returns nil.
+func GetSwagger(name string) Swagger {
+ swaggerMu.RLock()
+ defer swaggerMu.RUnlock()
+
+ return swags[name]
+}
+
+// ReadDoc reads swagger document. An optional name parameter can be passed to read a specific document.
+// The default name is "swagger".
+func ReadDoc(optionalName ...string) (string, error) {
+ swaggerMu.RLock()
+ defer swaggerMu.RUnlock()
+
+ if swags == nil {
+ return "", errors.New("no swag has yet been registered")
+ }
+
+ name := Name
+ if len(optionalName) != 0 && optionalName[0] != "" {
+ name = optionalName[0]
+ }
+
+ swag, ok := swags[name]
+ if !ok {
+ return "", fmt.Errorf("no swag named \"%s\" was registered", name)
+ }
+
+ return swag.ReadDoc(), nil
+}
diff --git a/vendor/github.com/swaggo/swag/types.go b/vendor/github.com/swaggo/swag/types.go
new file mode 100644
index 0000000..0076a6b
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/types.go
@@ -0,0 +1,105 @@
+package swag
+
+import (
+ "go/ast"
+ "go/token"
+ "regexp"
+ "strings"
+
+ "github.com/go-openapi/spec"
+)
+
+// Schema parsed 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
+}
+
+// TypeSpecDef the whole information of a typeSpec.
+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
+
+ NotUnique bool
+}
+
+// Name the name of the typeSpec.
+func (t *TypeSpecDef) Name() string {
+ if t.TypeSpec != nil && t.TypeSpec.Name != nil {
+ return t.TypeSpec.Name.Name
+ }
+
+ return ""
+}
+
+// TypeName the type name of the typeSpec.
+func (t *TypeSpecDef) TypeName() string {
+ if ignoreNameOverride(t.TypeSpec.Name.Name) {
+ return t.TypeSpec.Name.Name[1:]
+ } else if t.TypeSpec.Comment != nil {
+ // get alias from comment '// @name '
+ const regexCaseInsensitive = "(?i)"
+ reTypeName, err := regexp.Compile(regexCaseInsensitive + `^@name\s+(\S+)`)
+ if err != nil {
+ panic(err)
+ }
+ for _, comment := range t.TypeSpec.Comment.List {
+ trimmedComment := strings.TrimSpace(strings.TrimLeft(comment.Text, "/"))
+ texts := reTypeName.FindStringSubmatch(trimmedComment)
+ if len(texts) > 1 {
+ return texts[1]
+ }
+ }
+ }
+
+ var names []string
+ if t.NotUnique {
+ pkgPath := strings.Map(func(r rune) rune {
+ if r == '\\' || r == '/' || r == '.' {
+ return '_'
+ }
+ return r
+ }, t.PkgPath)
+ names = append(names, pkgPath)
+ } else if t.File != nil {
+ names = append(names, t.File.Name.Name)
+ }
+ if parentFun, ok := (t.ParentSpec).(*ast.FuncDecl); ok && parentFun != nil {
+ names = append(names, parentFun.Name.Name)
+ }
+ names = append(names, t.TypeSpec.Name.Name)
+ return fullTypeName(names...)
+}
+
+// FullPath return the full path of the typeSpec.
+func (t *TypeSpecDef) FullPath() string {
+ return t.PkgPath + "." + t.Name()
+}
+
+// AstFileInfo information of an ast.File.
+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
+}
diff --git a/vendor/github.com/swaggo/swag/utils.go b/vendor/github.com/swaggo/swag/utils.go
new file mode 100644
index 0000000..df31ff2
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/utils.go
@@ -0,0 +1,55 @@
+package swag
+
+import "unicode"
+
+// FieldsFunc split a string s by a func splitter into max n parts
+func FieldsFunc(s string, f func(rune2 rune) bool, n int) []string {
+ // A span is used to record a slice of s of the form s[start:end].
+ // The start index is inclusive and the end index is exclusive.
+ type span struct {
+ start int
+ end int
+ }
+ spans := make([]span, 0, 32)
+
+ // Find the field start and end indices.
+ // Doing this in a separate pass (rather than slicing the string s
+ // and collecting the result substrings right away) is significantly
+ // more efficient, possibly due to cache effects.
+ start := -1 // valid span start if >= 0
+ for end, rune := range s {
+ if f(rune) {
+ if start >= 0 {
+ spans = append(spans, span{start, end})
+ // Set start to a negative value.
+ // Note: using -1 here consistently and reproducibly
+ // slows down this code by a several percent on amd64.
+ start = ^start
+ }
+ } else {
+ if start < 0 {
+ start = end
+ if n > 0 && len(spans)+1 >= n {
+ break
+ }
+ }
+ }
+ }
+
+ // Last field might end at EOF.
+ if start >= 0 {
+ spans = append(spans, span{start, len(s)})
+ }
+
+ // Create strings from recorded field indices.
+ a := make([]string, len(spans))
+ for i, span := range spans {
+ a[i] = s[span.start:span.end]
+ }
+ return a
+}
+
+// FieldsByAnySpace split a string s by any space character into max n parts
+func FieldsByAnySpace(s string, n int) []string {
+ return FieldsFunc(s, unicode.IsSpace, n)
+}
diff --git a/vendor/github.com/swaggo/swag/version.go b/vendor/github.com/swaggo/swag/version.go
new file mode 100644
index 0000000..ff2810e
--- /dev/null
+++ b/vendor/github.com/swaggo/swag/version.go
@@ -0,0 +1,4 @@
+package swag
+
+// Version of swag.
+const Version = "v1.16.3"
diff --git a/vendor/github.com/valyala/fasttemplate/template.go b/vendor/github.com/valyala/fasttemplate/template.go
index c2df361..f2d3261 100644
--- a/vendor/github.com/valyala/fasttemplate/template.go
+++ b/vendor/github.com/valyala/fasttemplate/template.go
@@ -65,9 +65,9 @@ func ExecuteFunc(template, startTag, endTag string, w io.Writer, f TagFunc) (int
// values from the map m and writes the result to the given writer w.
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// Returns the number of bytes written to w.
//
@@ -81,9 +81,9 @@ func Execute(template, startTag, endTag string, w io.Writer, m map[string]interf
// This can be used as a drop-in replacement for strings.Replacer
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// Returns the number of bytes written to w.
//
@@ -134,9 +134,9 @@ var byteBufferPool bytebufferpool.Pool
// values from the map m and returns the result.
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// This function is optimized for constantly changing templates.
// Use Template.ExecuteString for frozen templates.
@@ -148,9 +148,9 @@ func ExecuteString(template, startTag, endTag string, m map[string]interface{})
// This can be used as a drop-in replacement for strings.Replacer
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// This function is optimized for constantly changing templates.
// Use Template.ExecuteStringStd for frozen templates.
@@ -304,9 +304,9 @@ func (t *Template) ExecuteFunc(w io.Writer, f TagFunc) (int64, error) {
// values from the map m and writes the result to the given writer w.
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// Returns the number of bytes written to w.
func (t *Template) Execute(w io.Writer, m map[string]interface{}) (int64, error) {
@@ -317,9 +317,9 @@ func (t *Template) Execute(w io.Writer, m map[string]interface{}) (int64, error)
// This can be used as a drop-in replacement for strings.Replacer
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// Returns the number of bytes written to w.
func (t *Template) ExecuteStd(w io.Writer, m map[string]interface{}) (int64, error) {
@@ -365,9 +365,9 @@ func (t *Template) ExecuteFuncStringWithErr(f TagFunc) (string, error) {
// values from the map m and returns the result.
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// This function is optimized for frozen templates.
// Use ExecuteString for constantly changing templates.
@@ -379,9 +379,9 @@ func (t *Template) ExecuteString(m map[string]interface{}) string {
// This can be used as a drop-in replacement for strings.Replacer
//
// Substitution map m may contain values with the following types:
-// - []byte - the fastest value type
-// - string - convenient value type
-// - TagFunc - flexible value type
+// * []byte - the fastest value type
+// * string - convenient value type
+// * TagFunc - flexible value type
//
// This function is optimized for frozen templates.
// Use ExecuteStringStd for constantly changing templates.
diff --git a/vendor/github.com/valyala/fasttemplate/unsafe.go b/vendor/github.com/valyala/fasttemplate/unsafe.go
index 1d0bc9e..1020ca3 100644
--- a/vendor/github.com/valyala/fasttemplate/unsafe.go
+++ b/vendor/github.com/valyala/fasttemplate/unsafe.go
@@ -1,4 +1,3 @@
-//go:build !appengine
// +build !appengine
package fasttemplate
diff --git a/vendor/golang.org/x/net/http/httpguts/httplex.go b/vendor/golang.org/x/net/http/httpguts/httplex.go
index 6e071e8..9b4de94 100644
--- a/vendor/golang.org/x/net/http/httpguts/httplex.go
+++ b/vendor/golang.org/x/net/http/httpguts/httplex.go
@@ -12,7 +12,7 @@ import (
"golang.org/x/net/idna"
)
-var isTokenTable = [127]bool{
+var isTokenTable = [256]bool{
'!': true,
'#': true,
'$': true,
@@ -93,12 +93,7 @@ var isTokenTable = [127]bool{
}
func IsTokenRune(r rune) bool {
- i := int(r)
- return i < len(isTokenTable) && isTokenTable[i]
-}
-
-func isNotToken(r rune) bool {
- return !IsTokenRune(r)
+ return r < utf8.RuneSelf && isTokenTable[byte(r)]
}
// HeaderValuesContainsToken reports whether any string in values
@@ -202,8 +197,8 @@ func ValidHeaderFieldName(v string) bool {
if len(v) == 0 {
return false
}
- for _, r := range v {
- if !IsTokenRune(r) {
+ for i := 0; i < len(v); i++ {
+ if !isTokenTable[v[i]] {
return false
}
}
diff --git a/vendor/golang.org/x/net/http2/frame.go b/vendor/golang.org/x/net/http2/frame.go
index c1f6b90..105c3b2 100644
--- a/vendor/golang.org/x/net/http2/frame.go
+++ b/vendor/golang.org/x/net/http2/frame.go
@@ -490,6 +490,9 @@ func terminalReadFrameError(err error) bool {
// returned error is ErrFrameTooLarge. Other errors may be of type
// ConnectionError, StreamError, or anything else from the underlying
// reader.
+//
+// If ReadFrame returns an error and a non-nil Frame, the Frame's StreamID
+// indicates the stream responsible for the error.
func (fr *Framer) ReadFrame() (Frame, error) {
fr.errDetail = nil
if fr.lastFrame != nil {
@@ -1510,19 +1513,18 @@ func (mh *MetaHeadersFrame) checkPseudos() error {
}
func (fr *Framer) maxHeaderStringLen() int {
- v := fr.maxHeaderListSize()
- if uint32(int(v)) == v {
- return int(v)
+ v := int(fr.maxHeaderListSize())
+ if v < 0 {
+ // If maxHeaderListSize overflows an int, use no limit (0).
+ return 0
}
- // They had a crazy big number for MaxHeaderBytes anyway,
- // so give them unlimited header lengths:
- return 0
+ return v
}
// readMetaFrame returns 0 or more CONTINUATION frames from fr and
// merge them into the provided hf and returns a MetaHeadersFrame
// with the decoded hpack values.
-func (fr *Framer) readMetaFrame(hf *HeadersFrame) (*MetaHeadersFrame, error) {
+func (fr *Framer) readMetaFrame(hf *HeadersFrame) (Frame, error) {
if fr.AllowIllegalReads {
return nil, errors.New("illegal use of AllowIllegalReads with ReadMetaHeaders")
}
@@ -1565,6 +1567,7 @@ func (fr *Framer) readMetaFrame(hf *HeadersFrame) (*MetaHeadersFrame, error) {
if size > remainSize {
hdec.SetEmitEnabled(false)
mh.Truncated = true
+ remainSize = 0
return
}
remainSize -= size
@@ -1577,8 +1580,38 @@ func (fr *Framer) readMetaFrame(hf *HeadersFrame) (*MetaHeadersFrame, error) {
var hc headersOrContinuation = hf
for {
frag := hc.HeaderBlockFragment()
+
+ // Avoid parsing large amounts of headers that we will then discard.
+ // If the sender exceeds the max header list size by too much,
+ // skip parsing the fragment and close the connection.
+ //
+ // "Too much" is either any CONTINUATION frame after we've already
+ // exceeded the max header list size (in which case remainSize is 0),
+ // or a frame whose encoded size is more than twice the remaining
+ // header list bytes we're willing to accept.
+ if int64(len(frag)) > int64(2*remainSize) {
+ if VerboseLogs {
+ log.Printf("http2: header list too large")
+ }
+ // It would be nice to send a RST_STREAM before sending the GOAWAY,
+ // but the structure of the server's frame writer makes this difficult.
+ return mh, ConnectionError(ErrCodeProtocol)
+ }
+
+ // Also close the connection after any CONTINUATION frame following an
+ // invalid header, since we stop tracking the size of the headers after
+ // an invalid one.
+ if invalid != nil {
+ if VerboseLogs {
+ log.Printf("http2: invalid header: %v", invalid)
+ }
+ // It would be nice to send a RST_STREAM before sending the GOAWAY,
+ // but the structure of the server's frame writer makes this difficult.
+ return mh, ConnectionError(ErrCodeProtocol)
+ }
+
if _, err := hdec.Write(frag); err != nil {
- return nil, ConnectionError(ErrCodeCompression)
+ return mh, ConnectionError(ErrCodeCompression)
}
if hc.HeadersEnded() {
@@ -1595,7 +1628,7 @@ func (fr *Framer) readMetaFrame(hf *HeadersFrame) (*MetaHeadersFrame, error) {
mh.HeadersFrame.invalidate()
if err := hdec.Close(); err != nil {
- return nil, ConnectionError(ErrCodeCompression)
+ return mh, ConnectionError(ErrCodeCompression)
}
if invalid != nil {
fr.errDetail = invalid
diff --git a/vendor/golang.org/x/net/http2/pipe.go b/vendor/golang.org/x/net/http2/pipe.go
index 684d984..3b9f06b 100644
--- a/vendor/golang.org/x/net/http2/pipe.go
+++ b/vendor/golang.org/x/net/http2/pipe.go
@@ -77,7 +77,10 @@ func (p *pipe) Read(d []byte) (n int, err error) {
}
}
-var errClosedPipeWrite = errors.New("write on closed buffer")
+var (
+ errClosedPipeWrite = errors.New("write on closed buffer")
+ errUninitializedPipeWrite = errors.New("write on uninitialized buffer")
+)
// Write copies bytes from p into the buffer and wakes a reader.
// It is an error to write more data than the buffer can hold.
@@ -91,6 +94,12 @@ func (p *pipe) Write(d []byte) (n int, err error) {
if p.err != nil || p.breakErr != nil {
return 0, errClosedPipeWrite
}
+ // pipe.setBuffer is never invoked, leaving the buffer uninitialized.
+ // We shouldn't try to write to an uninitialized pipe,
+ // but returning an error is better than panicking.
+ if p.b == nil {
+ return 0, errUninitializedPipeWrite
+ }
return p.b.Write(d)
}
diff --git a/vendor/golang.org/x/net/http2/server.go b/vendor/golang.org/x/net/http2/server.go
index ae94c64..c5d0810 100644
--- a/vendor/golang.org/x/net/http2/server.go
+++ b/vendor/golang.org/x/net/http2/server.go
@@ -124,6 +124,7 @@ type Server struct {
// IdleTimeout specifies how long until idle clients should be
// closed with a GOAWAY frame. PING frames are not considered
// activity for the purposes of IdleTimeout.
+ // If zero or negative, there is no timeout.
IdleTimeout time.Duration
// MaxUploadBufferPerConnection is the size of the initial flow
@@ -434,7 +435,7 @@ func (s *Server) ServeConn(c net.Conn, opts *ServeConnOpts) {
// passes the connection off to us with the deadline already set.
// Write deadlines are set per stream in serverConn.newStream.
// Disarm the net.Conn write deadline here.
- if sc.hs.WriteTimeout != 0 {
+ if sc.hs.WriteTimeout > 0 {
sc.conn.SetWriteDeadline(time.Time{})
}
@@ -731,11 +732,7 @@ func isClosedConnError(err error) bool {
return false
}
- // TODO: remove this string search and be more like the Windows
- // case below. That might involve modifying the standard library
- // to return better error types.
- str := err.Error()
- if strings.Contains(str, "use of closed network connection") {
+ if errors.Is(err, net.ErrClosed) {
return true
}
@@ -924,7 +921,7 @@ func (sc *serverConn) serve() {
sc.setConnState(http.StateActive)
sc.setConnState(http.StateIdle)
- if sc.srv.IdleTimeout != 0 {
+ if sc.srv.IdleTimeout > 0 {
sc.idleTimer = time.AfterFunc(sc.srv.IdleTimeout, sc.onIdleTimer)
defer sc.idleTimer.Stop()
}
@@ -1481,6 +1478,11 @@ func (sc *serverConn) processFrameFromReader(res readFrameResult) bool {
sc.goAway(ErrCodeFlowControl)
return true
case ConnectionError:
+ if res.f != nil {
+ if id := res.f.Header().StreamID; id > sc.maxClientStreamID {
+ sc.maxClientStreamID = id
+ }
+ }
sc.logf("http2: server connection error from %v: %v", sc.conn.RemoteAddr(), ev)
sc.goAway(ErrCode(ev))
return true // goAway will handle shutdown
@@ -1637,7 +1639,7 @@ func (sc *serverConn) closeStream(st *stream, err error) {
delete(sc.streams, st.id)
if len(sc.streams) == 0 {
sc.setConnState(http.StateIdle)
- if sc.srv.IdleTimeout != 0 {
+ if sc.srv.IdleTimeout > 0 {
sc.idleTimer.Reset(sc.srv.IdleTimeout)
}
if h1ServerKeepAlivesDisabled(sc.hs) {
@@ -2017,7 +2019,7 @@ func (sc *serverConn) processHeaders(f *MetaHeadersFrame) error {
// similar to how the http1 server works. Here it's
// technically more like the http1 Server's ReadHeaderTimeout
// (in Go 1.8), though. That's a more sane option anyway.
- if sc.hs.ReadTimeout != 0 {
+ if sc.hs.ReadTimeout > 0 {
sc.conn.SetReadDeadline(time.Time{})
st.readDeadline = time.AfterFunc(sc.hs.ReadTimeout, st.onReadTimeout)
}
@@ -2038,7 +2040,7 @@ func (sc *serverConn) upgradeRequest(req *http.Request) {
// Disable any read deadline set by the net/http package
// prior to the upgrade.
- if sc.hs.ReadTimeout != 0 {
+ if sc.hs.ReadTimeout > 0 {
sc.conn.SetReadDeadline(time.Time{})
}
@@ -2116,7 +2118,7 @@ func (sc *serverConn) newStream(id, pusherID uint32, state streamState) *stream
st.flow.conn = &sc.flow // link to conn-level counter
st.flow.add(sc.initialStreamSendWindowSize)
st.inflow.init(sc.srv.initialStreamRecvWindowSize())
- if sc.hs.WriteTimeout != 0 {
+ if sc.hs.WriteTimeout > 0 {
st.writeDeadline = time.AfterFunc(sc.hs.WriteTimeout, st.onWriteTimeout)
}
diff --git a/vendor/golang.org/x/net/http2/testsync.go b/vendor/golang.org/x/net/http2/testsync.go
new file mode 100644
index 0000000..61075bd
--- /dev/null
+++ b/vendor/golang.org/x/net/http2/testsync.go
@@ -0,0 +1,331 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package http2
+
+import (
+ "context"
+ "sync"
+ "time"
+)
+
+// testSyncHooks coordinates goroutines in tests.
+//
+// For example, a call to ClientConn.RoundTrip involves several goroutines, including:
+// - the goroutine running RoundTrip;
+// - the clientStream.doRequest goroutine, which writes the request; and
+// - the clientStream.readLoop goroutine, which reads the response.
+//
+// Using testSyncHooks, a test can start a RoundTrip and identify when all these goroutines
+// are blocked waiting for some condition such as reading the Request.Body or waiting for
+// flow control to become available.
+//
+// The testSyncHooks also manage timers and synthetic time in tests.
+// This permits us to, for example, start a request and cause it to time out waiting for
+// response headers without resorting to time.Sleep calls.
+type testSyncHooks struct {
+ // active/inactive act as a mutex and condition variable.
+ //
+ // - neither chan contains a value: testSyncHooks is locked.
+ // - active contains a value: unlocked, and at least one goroutine is not blocked
+ // - inactive contains a value: unlocked, and all goroutines are blocked
+ active chan struct{}
+ inactive chan struct{}
+
+ // goroutine counts
+ total int // total goroutines
+ condwait map[*sync.Cond]int // blocked in sync.Cond.Wait
+ blocked []*testBlockedGoroutine // otherwise blocked
+
+ // fake time
+ now time.Time
+ timers []*fakeTimer
+
+ // Transport testing: Report various events.
+ newclientconn func(*ClientConn)
+ newstream func(*clientStream)
+}
+
+// testBlockedGoroutine is a blocked goroutine.
+type testBlockedGoroutine struct {
+ f func() bool // blocked until f returns true
+ ch chan struct{} // closed when unblocked
+}
+
+func newTestSyncHooks() *testSyncHooks {
+ h := &testSyncHooks{
+ active: make(chan struct{}, 1),
+ inactive: make(chan struct{}, 1),
+ condwait: map[*sync.Cond]int{},
+ }
+ h.inactive <- struct{}{}
+ h.now = time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
+ return h
+}
+
+// lock acquires the testSyncHooks mutex.
+func (h *testSyncHooks) lock() {
+ select {
+ case <-h.active:
+ case <-h.inactive:
+ }
+}
+
+// waitInactive waits for all goroutines to become inactive.
+func (h *testSyncHooks) waitInactive() {
+ for {
+ <-h.inactive
+ if !h.unlock() {
+ break
+ }
+ }
+}
+
+// unlock releases the testSyncHooks mutex.
+// It reports whether any goroutines are active.
+func (h *testSyncHooks) unlock() (active bool) {
+ // Look for a blocked goroutine which can be unblocked.
+ blocked := h.blocked[:0]
+ unblocked := false
+ for _, b := range h.blocked {
+ if !unblocked && b.f() {
+ unblocked = true
+ close(b.ch)
+ } else {
+ blocked = append(blocked, b)
+ }
+ }
+ h.blocked = blocked
+
+ // Count goroutines blocked on condition variables.
+ condwait := 0
+ for _, count := range h.condwait {
+ condwait += count
+ }
+
+ if h.total > condwait+len(blocked) {
+ h.active <- struct{}{}
+ return true
+ } else {
+ h.inactive <- struct{}{}
+ return false
+ }
+}
+
+// goRun starts a new goroutine.
+func (h *testSyncHooks) goRun(f func()) {
+ h.lock()
+ h.total++
+ h.unlock()
+ go func() {
+ defer func() {
+ h.lock()
+ h.total--
+ h.unlock()
+ }()
+ f()
+ }()
+}
+
+// blockUntil indicates that a goroutine is blocked waiting for some condition to become true.
+// It waits until f returns true before proceeding.
+//
+// Example usage:
+//
+// h.blockUntil(func() bool {
+// // Is the context done yet?
+// select {
+// case <-ctx.Done():
+// default:
+// return false
+// }
+// return true
+// })
+// // Wait for the context to become done.
+// <-ctx.Done()
+//
+// The function f passed to blockUntil must be non-blocking and idempotent.
+func (h *testSyncHooks) blockUntil(f func() bool) {
+ if f() {
+ return
+ }
+ ch := make(chan struct{})
+ h.lock()
+ h.blocked = append(h.blocked, &testBlockedGoroutine{
+ f: f,
+ ch: ch,
+ })
+ h.unlock()
+ <-ch
+}
+
+// broadcast is sync.Cond.Broadcast.
+func (h *testSyncHooks) condBroadcast(cond *sync.Cond) {
+ h.lock()
+ delete(h.condwait, cond)
+ h.unlock()
+ cond.Broadcast()
+}
+
+// broadcast is sync.Cond.Wait.
+func (h *testSyncHooks) condWait(cond *sync.Cond) {
+ h.lock()
+ h.condwait[cond]++
+ h.unlock()
+}
+
+// newTimer creates a new fake timer.
+func (h *testSyncHooks) newTimer(d time.Duration) timer {
+ h.lock()
+ defer h.unlock()
+ t := &fakeTimer{
+ hooks: h,
+ when: h.now.Add(d),
+ c: make(chan time.Time),
+ }
+ h.timers = append(h.timers, t)
+ return t
+}
+
+// afterFunc creates a new fake AfterFunc timer.
+func (h *testSyncHooks) afterFunc(d time.Duration, f func()) timer {
+ h.lock()
+ defer h.unlock()
+ t := &fakeTimer{
+ hooks: h,
+ when: h.now.Add(d),
+ f: f,
+ }
+ h.timers = append(h.timers, t)
+ return t
+}
+
+func (h *testSyncHooks) contextWithTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
+ ctx, cancel := context.WithCancel(ctx)
+ t := h.afterFunc(d, cancel)
+ return ctx, func() {
+ t.Stop()
+ cancel()
+ }
+}
+
+func (h *testSyncHooks) timeUntilEvent() time.Duration {
+ h.lock()
+ defer h.unlock()
+ var next time.Time
+ for _, t := range h.timers {
+ if next.IsZero() || t.when.Before(next) {
+ next = t.when
+ }
+ }
+ if d := next.Sub(h.now); d > 0 {
+ return d
+ }
+ return 0
+}
+
+// advance advances time and causes synthetic timers to fire.
+func (h *testSyncHooks) advance(d time.Duration) {
+ h.lock()
+ defer h.unlock()
+ h.now = h.now.Add(d)
+ timers := h.timers[:0]
+ for _, t := range h.timers {
+ t := t // remove after go.mod depends on go1.22
+ t.mu.Lock()
+ switch {
+ case t.when.After(h.now):
+ timers = append(timers, t)
+ case t.when.IsZero():
+ // stopped timer
+ default:
+ t.when = time.Time{}
+ if t.c != nil {
+ close(t.c)
+ }
+ if t.f != nil {
+ h.total++
+ go func() {
+ defer func() {
+ h.lock()
+ h.total--
+ h.unlock()
+ }()
+ t.f()
+ }()
+ }
+ }
+ t.mu.Unlock()
+ }
+ h.timers = timers
+}
+
+// A timer wraps a time.Timer, or a synthetic equivalent in tests.
+// Unlike time.Timer, timer is single-use: The timer channel is closed when the timer expires.
+type timer interface {
+ C() <-chan time.Time
+ Stop() bool
+ Reset(d time.Duration) bool
+}
+
+// timeTimer implements timer using real time.
+type timeTimer struct {
+ t *time.Timer
+ c chan time.Time
+}
+
+// newTimeTimer creates a new timer using real time.
+func newTimeTimer(d time.Duration) timer {
+ ch := make(chan time.Time)
+ t := time.AfterFunc(d, func() {
+ close(ch)
+ })
+ return &timeTimer{t, ch}
+}
+
+// newTimeAfterFunc creates an AfterFunc timer using real time.
+func newTimeAfterFunc(d time.Duration, f func()) timer {
+ return &timeTimer{
+ t: time.AfterFunc(d, f),
+ }
+}
+
+func (t timeTimer) C() <-chan time.Time { return t.c }
+func (t timeTimer) Stop() bool { return t.t.Stop() }
+func (t timeTimer) Reset(d time.Duration) bool { return t.t.Reset(d) }
+
+// fakeTimer implements timer using fake time.
+type fakeTimer struct {
+ hooks *testSyncHooks
+
+ mu sync.Mutex
+ when time.Time // when the timer will fire
+ c chan time.Time // closed when the timer fires; mutually exclusive with f
+ f func() // called when the timer fires; mutually exclusive with c
+}
+
+func (t *fakeTimer) C() <-chan time.Time { return t.c }
+
+func (t *fakeTimer) Stop() bool {
+ t.mu.Lock()
+ defer t.mu.Unlock()
+ stopped := t.when.IsZero()
+ t.when = time.Time{}
+ return stopped
+}
+
+func (t *fakeTimer) Reset(d time.Duration) bool {
+ if t.c != nil || t.f == nil {
+ panic("fakeTimer only supports Reset on AfterFunc timers")
+ }
+ t.mu.Lock()
+ defer t.mu.Unlock()
+ t.hooks.lock()
+ defer t.hooks.unlock()
+ active := !t.when.IsZero()
+ t.when = t.hooks.now.Add(d)
+ if !active {
+ t.hooks.timers = append(t.hooks.timers, t)
+ }
+ return active
+}
diff --git a/vendor/golang.org/x/net/http2/transport.go b/vendor/golang.org/x/net/http2/transport.go
index df578b8..2fa4949 100644
--- a/vendor/golang.org/x/net/http2/transport.go
+++ b/vendor/golang.org/x/net/http2/transport.go
@@ -147,6 +147,12 @@ type Transport struct {
// waiting for their turn.
StrictMaxConcurrentStreams bool
+ // IdleConnTimeout is the maximum amount of time an idle
+ // (keep-alive) connection will remain idle before closing
+ // itself.
+ // Zero means no limit.
+ IdleConnTimeout time.Duration
+
// ReadIdleTimeout is the timeout after which a health check using ping
// frame will be carried out if no frame is received on the connection.
// Note that a ping response will is considered a received frame, so if
@@ -178,6 +184,8 @@ type Transport struct {
connPoolOnce sync.Once
connPoolOrDef ClientConnPool // non-nil version of ConnPool
+
+ syncHooks *testSyncHooks
}
func (t *Transport) maxHeaderListSize() uint32 {
@@ -302,7 +310,7 @@ type ClientConn struct {
readerErr error // set before readerDone is closed
idleTimeout time.Duration // or 0 for never
- idleTimer *time.Timer
+ idleTimer timer
mu sync.Mutex // guards following
cond *sync.Cond // hold mu; broadcast on flow/closed changes
@@ -344,6 +352,60 @@ type ClientConn struct {
werr error // first write error that has occurred
hbuf bytes.Buffer // HPACK encoder writes into this
henc *hpack.Encoder
+
+ syncHooks *testSyncHooks // can be nil
+}
+
+// Hook points used for testing.
+// Outside of tests, cc.syncHooks is nil and these all have minimal implementations.
+// Inside tests, see the testSyncHooks function docs.
+
+// goRun starts a new goroutine.
+func (cc *ClientConn) goRun(f func()) {
+ if cc.syncHooks != nil {
+ cc.syncHooks.goRun(f)
+ return
+ }
+ go f()
+}
+
+// condBroadcast is cc.cond.Broadcast.
+func (cc *ClientConn) condBroadcast() {
+ if cc.syncHooks != nil {
+ cc.syncHooks.condBroadcast(cc.cond)
+ }
+ cc.cond.Broadcast()
+}
+
+// condWait is cc.cond.Wait.
+func (cc *ClientConn) condWait() {
+ if cc.syncHooks != nil {
+ cc.syncHooks.condWait(cc.cond)
+ }
+ cc.cond.Wait()
+}
+
+// newTimer creates a new time.Timer, or a synthetic timer in tests.
+func (cc *ClientConn) newTimer(d time.Duration) timer {
+ if cc.syncHooks != nil {
+ return cc.syncHooks.newTimer(d)
+ }
+ return newTimeTimer(d)
+}
+
+// afterFunc creates a new time.AfterFunc timer, or a synthetic timer in tests.
+func (cc *ClientConn) afterFunc(d time.Duration, f func()) timer {
+ if cc.syncHooks != nil {
+ return cc.syncHooks.afterFunc(d, f)
+ }
+ return newTimeAfterFunc(d, f)
+}
+
+func (cc *ClientConn) contextWithTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
+ if cc.syncHooks != nil {
+ return cc.syncHooks.contextWithTimeout(ctx, d)
+ }
+ return context.WithTimeout(ctx, d)
}
// clientStream is the state for a single HTTP/2 stream. One of these
@@ -425,7 +487,7 @@ func (cs *clientStream) abortStreamLocked(err error) {
// TODO(dneil): Clean up tests where cs.cc.cond is nil.
if cs.cc.cond != nil {
// Wake up writeRequestBody if it is waiting on flow control.
- cs.cc.cond.Broadcast()
+ cs.cc.condBroadcast()
}
}
@@ -435,7 +497,7 @@ func (cs *clientStream) abortRequestBodyWrite() {
defer cc.mu.Unlock()
if cs.reqBody != nil && cs.reqBodyClosed == nil {
cs.closeReqBodyLocked()
- cc.cond.Broadcast()
+ cc.condBroadcast()
}
}
@@ -445,10 +507,10 @@ func (cs *clientStream) closeReqBodyLocked() {
}
cs.reqBodyClosed = make(chan struct{})
reqBodyClosed := cs.reqBodyClosed
- go func() {
+ cs.cc.goRun(func() {
cs.reqBody.Close()
close(reqBodyClosed)
- }()
+ })
}
type stickyErrWriter struct {
@@ -537,15 +599,6 @@ func authorityAddr(scheme string, authority string) (addr string) {
return net.JoinHostPort(host, port)
}
-var retryBackoffHook func(time.Duration) *time.Timer
-
-func backoffNewTimer(d time.Duration) *time.Timer {
- if retryBackoffHook != nil {
- return retryBackoffHook(d)
- }
- return time.NewTimer(d)
-}
-
// RoundTripOpt is like RoundTrip, but takes options.
func (t *Transport) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error) {
if !(req.URL.Scheme == "https" || (req.URL.Scheme == "http" && t.AllowHTTP)) {
@@ -573,13 +626,27 @@ func (t *Transport) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Res
backoff := float64(uint(1) << (uint(retry) - 1))
backoff += backoff * (0.1 * mathrand.Float64())
d := time.Second * time.Duration(backoff)
- timer := backoffNewTimer(d)
+ var tm timer
+ if t.syncHooks != nil {
+ tm = t.syncHooks.newTimer(d)
+ t.syncHooks.blockUntil(func() bool {
+ select {
+ case <-tm.C():
+ case <-req.Context().Done():
+ default:
+ return false
+ }
+ return true
+ })
+ } else {
+ tm = newTimeTimer(d)
+ }
select {
- case <-timer.C:
+ case <-tm.C():
t.vlogf("RoundTrip retrying after failure: %v", roundTripErr)
continue
case <-req.Context().Done():
- timer.Stop()
+ tm.Stop()
err = req.Context().Err()
}
}
@@ -658,6 +725,9 @@ func canRetryError(err error) bool {
}
func (t *Transport) dialClientConn(ctx context.Context, addr string, singleUse bool) (*ClientConn, error) {
+ if t.syncHooks != nil {
+ return t.newClientConn(nil, singleUse, t.syncHooks)
+ }
host, _, err := net.SplitHostPort(addr)
if err != nil {
return nil, err
@@ -666,7 +736,7 @@ func (t *Transport) dialClientConn(ctx context.Context, addr string, singleUse b
if err != nil {
return nil, err
}
- return t.newClientConn(tconn, singleUse)
+ return t.newClientConn(tconn, singleUse, nil)
}
func (t *Transport) newTLSConfig(host string) *tls.Config {
@@ -732,10 +802,10 @@ func (t *Transport) maxEncoderHeaderTableSize() uint32 {
}
func (t *Transport) NewClientConn(c net.Conn) (*ClientConn, error) {
- return t.newClientConn(c, t.disableKeepAlives())
+ return t.newClientConn(c, t.disableKeepAlives(), nil)
}
-func (t *Transport) newClientConn(c net.Conn, singleUse bool) (*ClientConn, error) {
+func (t *Transport) newClientConn(c net.Conn, singleUse bool, hooks *testSyncHooks) (*ClientConn, error) {
cc := &ClientConn{
t: t,
tconn: c,
@@ -750,10 +820,15 @@ func (t *Transport) newClientConn(c net.Conn, singleUse bool) (*ClientConn, erro
wantSettingsAck: true,
pings: make(map[[8]byte]chan struct{}),
reqHeaderMu: make(chan struct{}, 1),
+ syncHooks: hooks,
+ }
+ if hooks != nil {
+ hooks.newclientconn(cc)
+ c = cc.tconn
}
if d := t.idleConnTimeout(); d != 0 {
cc.idleTimeout = d
- cc.idleTimer = time.AfterFunc(d, cc.onIdleTimeout)
+ cc.idleTimer = cc.afterFunc(d, cc.onIdleTimeout)
}
if VerboseLogs {
t.vlogf("http2: Transport creating client conn %p to %v", cc, c.RemoteAddr())
@@ -818,7 +893,7 @@ func (t *Transport) newClientConn(c net.Conn, singleUse bool) (*ClientConn, erro
return nil, cc.werr
}
- go cc.readLoop()
+ cc.goRun(cc.readLoop)
return cc, nil
}
@@ -826,7 +901,7 @@ func (cc *ClientConn) healthCheck() {
pingTimeout := cc.t.pingTimeout()
// We don't need to periodically ping in the health check, because the readLoop of ClientConn will
// trigger the healthCheck again if there is no frame received.
- ctx, cancel := context.WithTimeout(context.Background(), pingTimeout)
+ ctx, cancel := cc.contextWithTimeout(context.Background(), pingTimeout)
defer cancel()
cc.vlogf("http2: Transport sending health check")
err := cc.Ping(ctx)
@@ -861,7 +936,20 @@ func (cc *ClientConn) setGoAway(f *GoAwayFrame) {
}
last := f.LastStreamID
for streamID, cs := range cc.streams {
- if streamID > last {
+ if streamID <= last {
+ // The server's GOAWAY indicates that it received this stream.
+ // It will either finish processing it, or close the connection
+ // without doing so. Either way, leave the stream alone for now.
+ continue
+ }
+ if streamID == 1 && cc.goAway.ErrCode != ErrCodeNo {
+ // Don't retry the first stream on a connection if we get a non-NO error.
+ // If the server is sending an error on a new connection,
+ // retrying the request on a new one probably isn't going to work.
+ cs.abortStreamLocked(fmt.Errorf("http2: Transport received GOAWAY from server ErrCode:%v", cc.goAway.ErrCode))
+ } else {
+ // Aborting the stream with errClentConnGotGoAway indicates that
+ // the request should be retried on a new connection.
cs.abortStreamLocked(errClientConnGotGoAway)
}
}
@@ -1056,7 +1144,7 @@ func (cc *ClientConn) Shutdown(ctx context.Context) error {
// Wait for all in-flight streams to complete or connection to close
done := make(chan struct{})
cancelled := false // guarded by cc.mu
- go func() {
+ cc.goRun(func() {
cc.mu.Lock()
defer cc.mu.Unlock()
for {
@@ -1068,9 +1156,9 @@ func (cc *ClientConn) Shutdown(ctx context.Context) error {
if cancelled {
break
}
- cc.cond.Wait()
+ cc.condWait()
}
- }()
+ })
shutdownEnterWaitStateHook()
select {
case <-done:
@@ -1080,7 +1168,7 @@ func (cc *ClientConn) Shutdown(ctx context.Context) error {
cc.mu.Lock()
// Free the goroutine above
cancelled = true
- cc.cond.Broadcast()
+ cc.condBroadcast()
cc.mu.Unlock()
return ctx.Err()
}
@@ -1118,7 +1206,7 @@ func (cc *ClientConn) closeForError(err error) {
for _, cs := range cc.streams {
cs.abortStreamLocked(err)
}
- cc.cond.Broadcast()
+ cc.condBroadcast()
cc.mu.Unlock()
cc.closeConn()
}
@@ -1215,6 +1303,10 @@ func (cc *ClientConn) decrStreamReservationsLocked() {
}
func (cc *ClientConn) RoundTrip(req *http.Request) (*http.Response, error) {
+ return cc.roundTrip(req, nil)
+}
+
+func (cc *ClientConn) roundTrip(req *http.Request, streamf func(*clientStream)) (*http.Response, error) {
ctx := req.Context()
cs := &clientStream{
cc: cc,
@@ -1229,9 +1321,23 @@ func (cc *ClientConn) RoundTrip(req *http.Request) (*http.Response, error) {
respHeaderRecv: make(chan struct{}),
donec: make(chan struct{}),
}
- go cs.doRequest(req)
+ cc.goRun(func() {
+ cs.doRequest(req)
+ })
waitDone := func() error {
+ if cc.syncHooks != nil {
+ cc.syncHooks.blockUntil(func() bool {
+ select {
+ case <-cs.donec:
+ case <-ctx.Done():
+ case <-cs.reqCancel:
+ default:
+ return false
+ }
+ return true
+ })
+ }
select {
case <-cs.donec:
return nil
@@ -1292,7 +1398,24 @@ func (cc *ClientConn) RoundTrip(req *http.Request) (*http.Response, error) {
return err
}
+ if streamf != nil {
+ streamf(cs)
+ }
+
for {
+ if cc.syncHooks != nil {
+ cc.syncHooks.blockUntil(func() bool {
+ select {
+ case <-cs.respHeaderRecv:
+ case <-cs.abort:
+ case <-ctx.Done():
+ case <-cs.reqCancel:
+ default:
+ return false
+ }
+ return true
+ })
+ }
select {
case <-cs.respHeaderRecv:
return handleResponseHeaders()
@@ -1348,6 +1471,21 @@ func (cs *clientStream) writeRequest(req *http.Request) (err error) {
if cc.reqHeaderMu == nil {
panic("RoundTrip on uninitialized ClientConn") // for tests
}
+ var newStreamHook func(*clientStream)
+ if cc.syncHooks != nil {
+ newStreamHook = cc.syncHooks.newstream
+ cc.syncHooks.blockUntil(func() bool {
+ select {
+ case cc.reqHeaderMu <- struct{}{}:
+ <-cc.reqHeaderMu
+ case <-cs.reqCancel:
+ case <-ctx.Done():
+ default:
+ return false
+ }
+ return true
+ })
+ }
select {
case cc.reqHeaderMu <- struct{}{}:
case <-cs.reqCancel:
@@ -1372,6 +1510,10 @@ func (cs *clientStream) writeRequest(req *http.Request) (err error) {
}
cc.mu.Unlock()
+ if newStreamHook != nil {
+ newStreamHook(cs)
+ }
+
// TODO(bradfitz): this is a copy of the logic in net/http. Unify somewhere?
if !cc.t.disableCompression() &&
req.Header.Get("Accept-Encoding") == "" &&
@@ -1452,15 +1594,30 @@ func (cs *clientStream) writeRequest(req *http.Request) (err error) {
var respHeaderTimer <-chan time.Time
var respHeaderRecv chan struct{}
if d := cc.responseHeaderTimeout(); d != 0 {
- timer := time.NewTimer(d)
+ timer := cc.newTimer(d)
defer timer.Stop()
- respHeaderTimer = timer.C
+ respHeaderTimer = timer.C()
respHeaderRecv = cs.respHeaderRecv
}
// Wait until the peer half-closes its end of the stream,
// or until the request is aborted (via context, error, or otherwise),
// whichever comes first.
for {
+ if cc.syncHooks != nil {
+ cc.syncHooks.blockUntil(func() bool {
+ select {
+ case <-cs.peerClosed:
+ case <-respHeaderTimer:
+ case <-respHeaderRecv:
+ case <-cs.abort:
+ case <-ctx.Done():
+ case <-cs.reqCancel:
+ default:
+ return false
+ }
+ return true
+ })
+ }
select {
case <-cs.peerClosed:
return nil
@@ -1609,7 +1766,7 @@ func (cc *ClientConn) awaitOpenSlotForStreamLocked(cs *clientStream) error {
return nil
}
cc.pendingRequests++
- cc.cond.Wait()
+ cc.condWait()
cc.pendingRequests--
select {
case <-cs.abort:
@@ -1871,10 +2028,26 @@ func (cs *clientStream) awaitFlowControl(maxBytes int) (taken int32, err error)
cs.flow.take(take)
return take, nil
}
- cc.cond.Wait()
+ cc.condWait()
}
}
+func validateHeaders(hdrs http.Header) string {
+ for k, vv := range hdrs {
+ if !httpguts.ValidHeaderFieldName(k) {
+ return fmt.Sprintf("name %q", k)
+ }
+ for _, v := range vv {
+ if !httpguts.ValidHeaderFieldValue(v) {
+ // Don't include the value in the error,
+ // because it may be sensitive.
+ return fmt.Sprintf("value for header %q", k)
+ }
+ }
+ }
+ return ""
+}
+
var errNilRequestURL = errors.New("http2: Request.URI is nil")
// requires cc.wmu be held.
@@ -1912,19 +2085,14 @@ func (cc *ClientConn) encodeHeaders(req *http.Request, addGzipHeader bool, trail
}
}
- // Check for any invalid headers and return an error before we
+ // Check for any invalid headers+trailers and return an error before we
// potentially pollute our hpack state. (We want to be able to
// continue to reuse the hpack encoder for future requests)
- for k, vv := range req.Header {
- if !httpguts.ValidHeaderFieldName(k) {
- return nil, fmt.Errorf("invalid HTTP header name %q", k)
- }
- for _, v := range vv {
- if !httpguts.ValidHeaderFieldValue(v) {
- // Don't include the value in the error, because it may be sensitive.
- return nil, fmt.Errorf("invalid HTTP header value for header %q", k)
- }
- }
+ if err := validateHeaders(req.Header); err != "" {
+ return nil, fmt.Errorf("invalid HTTP header %s", err)
+ }
+ if err := validateHeaders(req.Trailer); err != "" {
+ return nil, fmt.Errorf("invalid HTTP trailer %s", err)
}
enumerateHeaders := func(f func(name, value string)) {
@@ -2143,7 +2311,7 @@ func (cc *ClientConn) forgetStreamID(id uint32) {
}
// Wake up writeRequestBody via clientStream.awaitFlowControl and
// wake up RoundTrip if there is a pending request.
- cc.cond.Broadcast()
+ cc.condBroadcast()
closeOnIdle := cc.singleUse || cc.doNotReuse || cc.t.disableKeepAlives() || cc.goAway != nil
if closeOnIdle && cc.streamsReserved == 0 && len(cc.streams) == 0 {
@@ -2231,7 +2399,7 @@ func (rl *clientConnReadLoop) cleanup() {
cs.abortStreamLocked(err)
}
}
- cc.cond.Broadcast()
+ cc.condBroadcast()
cc.mu.Unlock()
}
@@ -2266,10 +2434,9 @@ func (rl *clientConnReadLoop) run() error {
cc := rl.cc
gotSettings := false
readIdleTimeout := cc.t.ReadIdleTimeout
- var t *time.Timer
+ var t timer
if readIdleTimeout != 0 {
- t = time.AfterFunc(readIdleTimeout, cc.healthCheck)
- defer t.Stop()
+ t = cc.afterFunc(readIdleTimeout, cc.healthCheck)
}
for {
f, err := cc.fr.ReadFrame()
@@ -2684,7 +2851,7 @@ func (rl *clientConnReadLoop) processData(f *DataFrame) error {
})
return nil
}
- if !cs.firstByte {
+ if !cs.pastHeaders {
cc.logf("protocol error: received DATA before a HEADERS frame")
rl.endStreamError(cs, StreamError{
StreamID: f.StreamID,
@@ -2867,7 +3034,7 @@ func (rl *clientConnReadLoop) processSettingsNoWrite(f *SettingsFrame) error {
for _, cs := range cc.streams {
cs.flow.add(delta)
}
- cc.cond.Broadcast()
+ cc.condBroadcast()
cc.initialWindowSize = s.Val
case SettingHeaderTableSize:
@@ -2911,9 +3078,18 @@ func (rl *clientConnReadLoop) processWindowUpdate(f *WindowUpdateFrame) error {
fl = &cs.flow
}
if !fl.add(int32(f.Increment)) {
+ // For stream, the sender sends RST_STREAM with an error code of FLOW_CONTROL_ERROR
+ if cs != nil {
+ rl.endStreamError(cs, StreamError{
+ StreamID: f.StreamID,
+ Code: ErrCodeFlowControl,
+ })
+ return nil
+ }
+
return ConnectionError(ErrCodeFlowControl)
}
- cc.cond.Broadcast()
+ cc.condBroadcast()
return nil
}
@@ -2955,24 +3131,38 @@ func (cc *ClientConn) Ping(ctx context.Context) error {
}
cc.mu.Unlock()
}
- errc := make(chan error, 1)
- go func() {
+ var pingError error
+ errc := make(chan struct{})
+ cc.goRun(func() {
cc.wmu.Lock()
defer cc.wmu.Unlock()
- if err := cc.fr.WritePing(false, p); err != nil {
- errc <- err
+ if pingError = cc.fr.WritePing(false, p); pingError != nil {
+ close(errc)
return
}
- if err := cc.bw.Flush(); err != nil {
- errc <- err
+ if pingError = cc.bw.Flush(); pingError != nil {
+ close(errc)
return
}
- }()
+ })
+ if cc.syncHooks != nil {
+ cc.syncHooks.blockUntil(func() bool {
+ select {
+ case <-c:
+ case <-errc:
+ case <-ctx.Done():
+ case <-cc.readerDone:
+ default:
+ return false
+ }
+ return true
+ })
+ }
select {
case <-c:
return nil
- case err := <-errc:
- return err
+ case <-errc:
+ return pingError
case <-ctx.Done():
return ctx.Err()
case <-cc.readerDone:
@@ -3141,9 +3331,17 @@ func (rt noDialH2RoundTripper) RoundTrip(req *http.Request) (*http.Response, err
}
func (t *Transport) idleConnTimeout() time.Duration {
+ // to keep things backwards compatible, we use non-zero values of
+ // IdleConnTimeout, followed by using the IdleConnTimeout on the underlying
+ // http1 transport, followed by 0
+ if t.IdleConnTimeout != 0 {
+ return t.IdleConnTimeout
+ }
+
if t.t1 != nil {
return t.t1.IdleConnTimeout
}
+
return 0
}
diff --git a/vendor/golang.org/x/sys/unix/aliases.go b/vendor/golang.org/x/sys/unix/aliases.go
index e7d3df4..b0e4198 100644
--- a/vendor/golang.org/x/sys/unix/aliases.go
+++ b/vendor/golang.org/x/sys/unix/aliases.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-//go:build (aix || darwin || dragonfly || freebsd || linux || netbsd || openbsd || solaris || zos) && go1.9
+//go:build aix || darwin || dragonfly || freebsd || linux || netbsd || openbsd || solaris || zos
package unix
diff --git a/vendor/golang.org/x/sys/unix/asm_zos_s390x.s b/vendor/golang.org/x/sys/unix/asm_zos_s390x.s
index 2f67ba8..813dfad 100644
--- a/vendor/golang.org/x/sys/unix/asm_zos_s390x.s
+++ b/vendor/golang.org/x/sys/unix/asm_zos_s390x.s
@@ -9,9 +9,11 @@
#define PSALAA 1208(R0)
#define GTAB64(x) 80(x)
#define LCA64(x) 88(x)
+#define SAVSTACK_ASYNC(x) 336(x) // in the LCA
#define CAA(x) 8(x)
-#define EDCHPXV(x) 1016(x) // in the CAA
-#define SAVSTACK_ASYNC(x) 336(x) // in the LCA
+#define CEECAATHDID(x) 976(x) // in the CAA
+#define EDCHPXV(x) 1016(x) // in the CAA
+#define GOCB(x) 1104(x) // in the CAA
// SS_*, where x=SAVSTACK_ASYNC
#define SS_LE(x) 0(x)
@@ -19,394 +21,125 @@
#define SS_ERRNO(x) 16(x)
#define SS_ERRNOJR(x) 20(x)
-#define LE_CALL BYTE $0x0D; BYTE $0x76; // BL R7, R6
+// Function Descriptor Offsets
+#define __errno 0x156*16
+#define __err2ad 0x16C*16
-TEXT ·clearErrno(SB),NOSPLIT,$0-0
- BL addrerrno<>(SB)
- MOVD $0, 0(R3)
+// Call Instructions
+#define LE_CALL BYTE $0x0D; BYTE $0x76 // BL R7, R6
+#define SVC_LOAD BYTE $0x0A; BYTE $0x08 // SVC 08 LOAD
+#define SVC_DELETE BYTE $0x0A; BYTE $0x09 // SVC 09 DELETE
+
+DATA zosLibVec<>(SB)/8, $0
+GLOBL zosLibVec<>(SB), NOPTR, $8
+
+TEXT ·initZosLibVec(SB), NOSPLIT|NOFRAME, $0-0
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
+ MOVD CAA(R8), R8
+ MOVD EDCHPXV(R8), R8
+ MOVD R8, zosLibVec<>(SB)
+ RET
+
+TEXT ·GetZosLibVec(SB), NOSPLIT|NOFRAME, $0-0
+ MOVD zosLibVec<>(SB), R8
+ MOVD R8, ret+0(FP)
+ RET
+
+TEXT ·clearErrno(SB), NOSPLIT, $0-0
+ BL addrerrno<>(SB)
+ MOVD $0, 0(R3)
RET
// Returns the address of errno in R3.
-TEXT addrerrno<>(SB),NOSPLIT|NOFRAME,$0-0
+TEXT addrerrno<>(SB), NOSPLIT|NOFRAME, $0-0
// Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
// Get __errno FuncDesc.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- ADD $(0x156*16), R9
- LMG 0(R9), R5, R6
+ MOVD CAA(R8), R9
+ MOVD EDCHPXV(R9), R9
+ ADD $(__errno), R9
+ LMG 0(R9), R5, R6
// Switch to saved LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
+ MOVD SAVSTACK_ASYNC(R8), R9
+ MOVD 0(R9), R4
+ MOVD $0, 0(R9)
// Call __errno function.
LE_CALL
NOPH
// Switch back to Go stack.
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
- RET
-
-TEXT ·syscall_syscall(SB),NOSPLIT,$0-56
- BL runtime·entersyscall(SB)
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+32(FP)
- MOVD R0, r2+40(FP)
- MOVD R0, err+48(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL addrerrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+48(FP)
-done:
- BL runtime·exitsyscall(SB)
- RET
-
-TEXT ·syscall_rawsyscall(SB),NOSPLIT,$0-56
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+32(FP)
- MOVD R0, r2+40(FP)
- MOVD R0, err+48(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL addrerrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+48(FP)
-done:
- RET
-
-TEXT ·syscall_syscall6(SB),NOSPLIT,$0-80
- BL runtime·entersyscall(SB)
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Fill in parameter list.
- MOVD a4+32(FP), R12
- MOVD R12, (2176+24)(R4)
- MOVD a5+40(FP), R12
- MOVD R12, (2176+32)(R4)
- MOVD a6+48(FP), R12
- MOVD R12, (2176+40)(R4)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+56(FP)
- MOVD R0, r2+64(FP)
- MOVD R0, err+72(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL addrerrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+72(FP)
-done:
- BL runtime·exitsyscall(SB)
- RET
-
-TEXT ·syscall_rawsyscall6(SB),NOSPLIT,$0-80
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Fill in parameter list.
- MOVD a4+32(FP), R12
- MOVD R12, (2176+24)(R4)
- MOVD a5+40(FP), R12
- MOVD R12, (2176+32)(R4)
- MOVD a6+48(FP), R12
- MOVD R12, (2176+40)(R4)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+56(FP)
- MOVD R0, r2+64(FP)
- MOVD R0, err+72(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL ·rrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+72(FP)
-done:
- RET
-
-TEXT ·syscall_syscall9(SB),NOSPLIT,$0
- BL runtime·entersyscall(SB)
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Fill in parameter list.
- MOVD a4+32(FP), R12
- MOVD R12, (2176+24)(R4)
- MOVD a5+40(FP), R12
- MOVD R12, (2176+32)(R4)
- MOVD a6+48(FP), R12
- MOVD R12, (2176+40)(R4)
- MOVD a7+56(FP), R12
- MOVD R12, (2176+48)(R4)
- MOVD a8+64(FP), R12
- MOVD R12, (2176+56)(R4)
- MOVD a9+72(FP), R12
- MOVD R12, (2176+64)(R4)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+80(FP)
- MOVD R0, r2+88(FP)
- MOVD R0, err+96(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL addrerrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+96(FP)
-done:
- BL runtime·exitsyscall(SB)
- RET
-
-TEXT ·syscall_rawsyscall9(SB),NOSPLIT,$0
- MOVD a1+8(FP), R1
- MOVD a2+16(FP), R2
- MOVD a3+24(FP), R3
-
- // Get library control area (LCA).
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
-
- // Get function.
- MOVD CAA(R8), R9
- MOVD EDCHPXV(R9), R9
- MOVD trap+0(FP), R5
- SLD $4, R5
- ADD R5, R9
- LMG 0(R9), R5, R6
-
- // Restore LE stack.
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R4
- MOVD $0, 0(R9)
-
- // Fill in parameter list.
- MOVD a4+32(FP), R12
- MOVD R12, (2176+24)(R4)
- MOVD a5+40(FP), R12
- MOVD R12, (2176+32)(R4)
- MOVD a6+48(FP), R12
- MOVD R12, (2176+40)(R4)
- MOVD a7+56(FP), R12
- MOVD R12, (2176+48)(R4)
- MOVD a8+64(FP), R12
- MOVD R12, (2176+56)(R4)
- MOVD a9+72(FP), R12
- MOVD R12, (2176+64)(R4)
-
- // Call function.
- LE_CALL
- NOPH
- XOR R0, R0 // Restore R0 to $0.
- MOVD R4, 0(R9) // Save stack pointer.
-
- MOVD R3, r1+80(FP)
- MOVD R0, r2+88(FP)
- MOVD R0, err+96(FP)
- MOVW R3, R4
- CMP R4, $-1
- BNE done
- BL addrerrno<>(SB)
- MOVWZ 0(R3), R3
- MOVD R3, err+96(FP)
-done:
+ XOR R0, R0 // Restore R0 to $0.
+ MOVD R4, 0(R9) // Save stack pointer.
RET
// func svcCall(fnptr unsafe.Pointer, argv *unsafe.Pointer, dsa *uint64)
-TEXT ·svcCall(SB),NOSPLIT,$0
- BL runtime·save_g(SB) // Save g and stack pointer
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD R15, 0(R9)
+TEXT ·svcCall(SB), NOSPLIT, $0
+ BL runtime·save_g(SB) // Save g and stack pointer
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
+ MOVD SAVSTACK_ASYNC(R8), R9
+ MOVD R15, 0(R9)
- MOVD argv+8(FP), R1 // Move function arguments into registers
- MOVD dsa+16(FP), g
- MOVD fnptr+0(FP), R15
+ MOVD argv+8(FP), R1 // Move function arguments into registers
+ MOVD dsa+16(FP), g
+ MOVD fnptr+0(FP), R15
- BYTE $0x0D // Branch to function
- BYTE $0xEF
+ BYTE $0x0D // Branch to function
+ BYTE $0xEF
- BL runtime·load_g(SB) // Restore g and stack pointer
- MOVW PSALAA, R8
- MOVD LCA64(R8), R8
- MOVD SAVSTACK_ASYNC(R8), R9
- MOVD 0(R9), R15
+ BL runtime·load_g(SB) // Restore g and stack pointer
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
+ MOVD SAVSTACK_ASYNC(R8), R9
+ MOVD 0(R9), R15
RET
// func svcLoad(name *byte) unsafe.Pointer
-TEXT ·svcLoad(SB),NOSPLIT,$0
- MOVD R15, R2 // Save go stack pointer
- MOVD name+0(FP), R0 // Move SVC args into registers
- MOVD $0x80000000, R1
- MOVD $0, R15
- BYTE $0x0A // SVC 08 LOAD
- BYTE $0x08
- MOVW R15, R3 // Save return code from SVC
- MOVD R2, R15 // Restore go stack pointer
- CMP R3, $0 // Check SVC return code
- BNE error
+TEXT ·svcLoad(SB), NOSPLIT, $0
+ MOVD R15, R2 // Save go stack pointer
+ MOVD name+0(FP), R0 // Move SVC args into registers
+ MOVD $0x80000000, R1
+ MOVD $0, R15
+ SVC_LOAD
+ MOVW R15, R3 // Save return code from SVC
+ MOVD R2, R15 // Restore go stack pointer
+ CMP R3, $0 // Check SVC return code
+ BNE error
- MOVD $-2, R3 // Reset last bit of entry point to zero
- AND R0, R3
- MOVD R3, addr+8(FP) // Return entry point returned by SVC
- CMP R0, R3 // Check if last bit of entry point was set
- BNE done
+ MOVD $-2, R3 // Reset last bit of entry point to zero
+ AND R0, R3
+ MOVD R3, ret+8(FP) // Return entry point returned by SVC
+ CMP R0, R3 // Check if last bit of entry point was set
+ BNE done
- MOVD R15, R2 // Save go stack pointer
- MOVD $0, R15 // Move SVC args into registers (entry point still in r0 from SVC 08)
- BYTE $0x0A // SVC 09 DELETE
- BYTE $0x09
- MOVD R2, R15 // Restore go stack pointer
+ MOVD R15, R2 // Save go stack pointer
+ MOVD $0, R15 // Move SVC args into registers (entry point still in r0 from SVC 08)
+ SVC_DELETE
+ MOVD R2, R15 // Restore go stack pointer
error:
- MOVD $0, addr+8(FP) // Return 0 on failure
+ MOVD $0, ret+8(FP) // Return 0 on failure
+
done:
- XOR R0, R0 // Reset r0 to 0
+ XOR R0, R0 // Reset r0 to 0
RET
// func svcUnload(name *byte, fnptr unsafe.Pointer) int64
-TEXT ·svcUnload(SB),NOSPLIT,$0
- MOVD R15, R2 // Save go stack pointer
- MOVD name+0(FP), R0 // Move SVC args into registers
- MOVD addr+8(FP), R15
- BYTE $0x0A // SVC 09
- BYTE $0x09
- XOR R0, R0 // Reset r0 to 0
- MOVD R15, R1 // Save SVC return code
- MOVD R2, R15 // Restore go stack pointer
- MOVD R1, rc+0(FP) // Return SVC return code
+TEXT ·svcUnload(SB), NOSPLIT, $0
+ MOVD R15, R2 // Save go stack pointer
+ MOVD name+0(FP), R0 // Move SVC args into registers
+ MOVD fnptr+8(FP), R15
+ SVC_DELETE
+ XOR R0, R0 // Reset r0 to 0
+ MOVD R15, R1 // Save SVC return code
+ MOVD R2, R15 // Restore go stack pointer
+ MOVD R1, ret+16(FP) // Return SVC return code
RET
// func gettid() uint64
@@ -417,7 +150,233 @@ TEXT ·gettid(SB), NOSPLIT, $0
// Get CEECAATHDID
MOVD CAA(R8), R9
- MOVD 0x3D0(R9), R9
+ MOVD CEECAATHDID(R9), R9
MOVD R9, ret+0(FP)
RET
+
+//
+// Call LE function, if the return is -1
+// errno and errno2 is retrieved
+//
+TEXT ·CallLeFuncWithErr(SB), NOSPLIT, $0
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
+ MOVD CAA(R8), R9
+ MOVD g, GOCB(R9)
+
+ // Restore LE stack.
+ MOVD SAVSTACK_ASYNC(R8), R9 // R9-> LE stack frame saving address
+ MOVD 0(R9), R4 // R4-> restore previously saved stack frame pointer
+
+ MOVD parms_base+8(FP), R7 // R7 -> argument array
+ MOVD parms_len+16(FP), R8 // R8 number of arguments
+
+ // arg 1 ---> R1
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ MOVD 0(R7), R1
+
+ // arg 2 ---> R2
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ ADD $8, R7
+ MOVD 0(R7), R2
+
+ // arg 3 --> R3
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ ADD $8, R7
+ MOVD 0(R7), R3
+
+ CMP R8, $0
+ BEQ docall
+ MOVD $2176+16, R6 // starting LE stack address-8 to store 4th argument
+
+repeat:
+ ADD $8, R7
+ MOVD 0(R7), R0 // advance arg pointer by 8 byte
+ ADD $8, R6 // advance LE argument address by 8 byte
+ MOVD R0, (R4)(R6*1) // copy argument from go-slice to le-frame
+ SUB $1, R8
+ CMP R8, $0
+ BNE repeat
+
+docall:
+ MOVD funcdesc+0(FP), R8 // R8-> function descriptor
+ LMG 0(R8), R5, R6
+ MOVD $0, 0(R9) // R9 address of SAVSTACK_ASYNC
+ LE_CALL // balr R7, R6 (return #1)
+ NOPH
+ MOVD R3, ret+32(FP)
+ CMP R3, $-1 // compare result to -1
+ BNE done
+
+ // retrieve errno and errno2
+ MOVD zosLibVec<>(SB), R8
+ ADD $(__errno), R8
+ LMG 0(R8), R5, R6
+ LE_CALL // balr R7, R6 __errno (return #3)
+ NOPH
+ MOVWZ 0(R3), R3
+ MOVD R3, err+48(FP)
+ MOVD zosLibVec<>(SB), R8
+ ADD $(__err2ad), R8
+ LMG 0(R8), R5, R6
+ LE_CALL // balr R7, R6 __err2ad (return #2)
+ NOPH
+ MOVW (R3), R2 // retrieve errno2
+ MOVD R2, errno2+40(FP) // store in return area
+
+done:
+ MOVD R4, 0(R9) // Save stack pointer.
+ RET
+
+//
+// Call LE function, if the return is 0
+// errno and errno2 is retrieved
+//
+TEXT ·CallLeFuncWithPtrReturn(SB), NOSPLIT, $0
+ MOVW PSALAA, R8
+ MOVD LCA64(R8), R8
+ MOVD CAA(R8), R9
+ MOVD g, GOCB(R9)
+
+ // Restore LE stack.
+ MOVD SAVSTACK_ASYNC(R8), R9 // R9-> LE stack frame saving address
+ MOVD 0(R9), R4 // R4-> restore previously saved stack frame pointer
+
+ MOVD parms_base+8(FP), R7 // R7 -> argument array
+ MOVD parms_len+16(FP), R8 // R8 number of arguments
+
+ // arg 1 ---> R1
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ MOVD 0(R7), R1
+
+ // arg 2 ---> R2
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ ADD $8, R7
+ MOVD 0(R7), R2
+
+ // arg 3 --> R3
+ CMP R8, $0
+ BEQ docall
+ SUB $1, R8
+ ADD $8, R7
+ MOVD 0(R7), R3
+
+ CMP R8, $0
+ BEQ docall
+ MOVD $2176+16, R6 // starting LE stack address-8 to store 4th argument
+
+repeat:
+ ADD $8, R7
+ MOVD 0(R7), R0 // advance arg pointer by 8 byte
+ ADD $8, R6 // advance LE argument address by 8 byte
+ MOVD R0, (R4)(R6*1) // copy argument from go-slice to le-frame
+ SUB $1, R8
+ CMP R8, $0
+ BNE repeat
+
+docall:
+ MOVD funcdesc+0(FP), R8 // R8-> function descriptor
+ LMG 0(R8), R5, R6
+ MOVD $0, 0(R9) // R9 address of SAVSTACK_ASYNC
+ LE_CALL // balr R7, R6 (return #1)
+ NOPH
+ MOVD R3, ret+32(FP)
+ CMP R3, $0 // compare result to 0
+ BNE done
+
+ // retrieve errno and errno2
+ MOVD zosLibVec<>(SB), R8
+ ADD $(__errno), R8
+ LMG 0(R8), R5, R6
+ LE_CALL // balr R7, R6 __errno (return #3)
+ NOPH
+ MOVWZ 0(R3), R3
+ MOVD R3, err+48(FP)
+ MOVD zosLibVec<>(SB), R8
+ ADD $(__err2ad), R8
+ LMG 0(R8), R5, R6
+ LE_CALL // balr R7, R6 __err2ad (return #2)
+ NOPH
+ MOVW (R3), R2 // retrieve errno2
+ MOVD R2, errno2+40(FP) // store in return area
+ XOR R2, R2
+ MOVWZ R2, (R3) // clear errno2
+
+done:
+ MOVD R4, 0(R9) // Save stack pointer.
+ RET
+
+//
+// function to test if a pointer can be safely dereferenced (content read)
+// return 0 for succces
+//
+TEXT ·ptrtest(SB), NOSPLIT, $0-16
+ MOVD arg+0(FP), R10 // test pointer in R10
+
+ // set up R2 to point to CEECAADMC
+ BYTE $0xE3; BYTE $0x20; BYTE $0x04; BYTE $0xB8; BYTE $0x00; BYTE $0x17 // llgt 2,1208
+ BYTE $0xB9; BYTE $0x17; BYTE $0x00; BYTE $0x22 // llgtr 2,2
+ BYTE $0xA5; BYTE $0x26; BYTE $0x7F; BYTE $0xFF // nilh 2,32767
+ BYTE $0xE3; BYTE $0x22; BYTE $0x00; BYTE $0x58; BYTE $0x00; BYTE $0x04 // lg 2,88(2)
+ BYTE $0xE3; BYTE $0x22; BYTE $0x00; BYTE $0x08; BYTE $0x00; BYTE $0x04 // lg 2,8(2)
+ BYTE $0x41; BYTE $0x22; BYTE $0x03; BYTE $0x68 // la 2,872(2)
+
+ // set up R5 to point to the "shunt" path which set 1 to R3 (failure)
+ BYTE $0xB9; BYTE $0x82; BYTE $0x00; BYTE $0x33 // xgr 3,3
+ BYTE $0xA7; BYTE $0x55; BYTE $0x00; BYTE $0x04 // bras 5,lbl1
+ BYTE $0xA7; BYTE $0x39; BYTE $0x00; BYTE $0x01 // lghi 3,1
+
+ // if r3 is not zero (failed) then branch to finish
+ BYTE $0xB9; BYTE $0x02; BYTE $0x00; BYTE $0x33 // lbl1 ltgr 3,3
+ BYTE $0xA7; BYTE $0x74; BYTE $0x00; BYTE $0x08 // brc b'0111',lbl2
+
+ // stomic store shunt address in R5 into CEECAADMC
+ BYTE $0xE3; BYTE $0x52; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x24 // stg 5,0(2)
+
+ // now try reading from the test pointer in R10, if it fails it branches to the "lghi" instruction above
+ BYTE $0xE3; BYTE $0x9A; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x04 // lg 9,0(10)
+
+ // finish here, restore 0 into CEECAADMC
+ BYTE $0xB9; BYTE $0x82; BYTE $0x00; BYTE $0x99 // lbl2 xgr 9,9
+ BYTE $0xE3; BYTE $0x92; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x24 // stg 9,0(2)
+ MOVD R3, ret+8(FP) // result in R3
+ RET
+
+//
+// function to test if a untptr can be loaded from a pointer
+// return 1: the 8-byte content
+// 2: 0 for success, 1 for failure
+//
+// func safeload(ptr uintptr) ( value uintptr, error uintptr)
+TEXT ·safeload(SB), NOSPLIT, $0-24
+ MOVD ptr+0(FP), R10 // test pointer in R10
+ MOVD $0x0, R6
+ BYTE $0xE3; BYTE $0x20; BYTE $0x04; BYTE $0xB8; BYTE $0x00; BYTE $0x17 // llgt 2,1208
+ BYTE $0xB9; BYTE $0x17; BYTE $0x00; BYTE $0x22 // llgtr 2,2
+ BYTE $0xA5; BYTE $0x26; BYTE $0x7F; BYTE $0xFF // nilh 2,32767
+ BYTE $0xE3; BYTE $0x22; BYTE $0x00; BYTE $0x58; BYTE $0x00; BYTE $0x04 // lg 2,88(2)
+ BYTE $0xE3; BYTE $0x22; BYTE $0x00; BYTE $0x08; BYTE $0x00; BYTE $0x04 // lg 2,8(2)
+ BYTE $0x41; BYTE $0x22; BYTE $0x03; BYTE $0x68 // la 2,872(2)
+ BYTE $0xB9; BYTE $0x82; BYTE $0x00; BYTE $0x33 // xgr 3,3
+ BYTE $0xA7; BYTE $0x55; BYTE $0x00; BYTE $0x04 // bras 5,lbl1
+ BYTE $0xA7; BYTE $0x39; BYTE $0x00; BYTE $0x01 // lghi 3,1
+ BYTE $0xB9; BYTE $0x02; BYTE $0x00; BYTE $0x33 // lbl1 ltgr 3,3
+ BYTE $0xA7; BYTE $0x74; BYTE $0x00; BYTE $0x08 // brc b'0111',lbl2
+ BYTE $0xE3; BYTE $0x52; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x24 // stg 5,0(2)
+ BYTE $0xE3; BYTE $0x6A; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x04 // lg 6,0(10)
+ BYTE $0xB9; BYTE $0x82; BYTE $0x00; BYTE $0x99 // lbl2 xgr 9,9
+ BYTE $0xE3; BYTE $0x92; BYTE $0x00; BYTE $0x00; BYTE $0x00; BYTE $0x24 // stg 9,0(2)
+ MOVD R6, value+8(FP) // result in R6
+ MOVD R3, error+16(FP) // error in R3
+ RET
diff --git a/vendor/golang.org/x/sys/unix/bpxsvc_zos.go b/vendor/golang.org/x/sys/unix/bpxsvc_zos.go
new file mode 100644
index 0000000..39d647d
--- /dev/null
+++ b/vendor/golang.org/x/sys/unix/bpxsvc_zos.go
@@ -0,0 +1,657 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build zos
+
+package unix
+
+import (
+ "bytes"
+ "fmt"
+ "unsafe"
+)
+
+//go:noescape
+func bpxcall(plist []unsafe.Pointer, bpx_offset int64)
+
+//go:noescape
+func A2e([]byte)
+
+//go:noescape
+func E2a([]byte)
+
+const (
+ BPX4STA = 192 // stat
+ BPX4FST = 104 // fstat
+ BPX4LST = 132 // lstat
+ BPX4OPN = 156 // open
+ BPX4CLO = 72 // close
+ BPX4CHR = 500 // chattr
+ BPX4FCR = 504 // fchattr
+ BPX4LCR = 1180 // lchattr
+ BPX4CTW = 492 // cond_timed_wait
+ BPX4GTH = 1056 // __getthent
+ BPX4PTQ = 412 // pthread_quiesc
+ BPX4PTR = 320 // ptrace
+)
+
+const (
+ //options
+ //byte1
+ BPX_OPNFHIGH = 0x80
+ //byte2
+ BPX_OPNFEXEC = 0x80
+ //byte3
+ BPX_O_NOLARGEFILE = 0x08
+ BPX_O_LARGEFILE = 0x04
+ BPX_O_ASYNCSIG = 0x02
+ BPX_O_SYNC = 0x01
+ //byte4
+ BPX_O_CREXCL = 0xc0
+ BPX_O_CREAT = 0x80
+ BPX_O_EXCL = 0x40
+ BPX_O_NOCTTY = 0x20
+ BPX_O_TRUNC = 0x10
+ BPX_O_APPEND = 0x08
+ BPX_O_NONBLOCK = 0x04
+ BPX_FNDELAY = 0x04
+ BPX_O_RDWR = 0x03
+ BPX_O_RDONLY = 0x02
+ BPX_O_WRONLY = 0x01
+ BPX_O_ACCMODE = 0x03
+ BPX_O_GETFL = 0x0f
+
+ //mode
+ // byte1 (file type)
+ BPX_FT_DIR = 1
+ BPX_FT_CHARSPEC = 2
+ BPX_FT_REGFILE = 3
+ BPX_FT_FIFO = 4
+ BPX_FT_SYMLINK = 5
+ BPX_FT_SOCKET = 6
+ //byte3
+ BPX_S_ISUID = 0x08
+ BPX_S_ISGID = 0x04
+ BPX_S_ISVTX = 0x02
+ BPX_S_IRWXU1 = 0x01
+ BPX_S_IRUSR = 0x01
+ //byte4
+ BPX_S_IRWXU2 = 0xc0
+ BPX_S_IWUSR = 0x80
+ BPX_S_IXUSR = 0x40
+ BPX_S_IRWXG = 0x38
+ BPX_S_IRGRP = 0x20
+ BPX_S_IWGRP = 0x10
+ BPX_S_IXGRP = 0x08
+ BPX_S_IRWXOX = 0x07
+ BPX_S_IROTH = 0x04
+ BPX_S_IWOTH = 0x02
+ BPX_S_IXOTH = 0x01
+
+ CW_INTRPT = 1
+ CW_CONDVAR = 32
+ CW_TIMEOUT = 64
+
+ PGTHA_NEXT = 2
+ PGTHA_CURRENT = 1
+ PGTHA_FIRST = 0
+ PGTHA_LAST = 3
+ PGTHA_PROCESS = 0x80
+ PGTHA_CONTTY = 0x40
+ PGTHA_PATH = 0x20
+ PGTHA_COMMAND = 0x10
+ PGTHA_FILEDATA = 0x08
+ PGTHA_THREAD = 0x04
+ PGTHA_PTAG = 0x02
+ PGTHA_COMMANDLONG = 0x01
+ PGTHA_THREADFAST = 0x80
+ PGTHA_FILEPATH = 0x40
+ PGTHA_THDSIGMASK = 0x20
+ // thread quiece mode
+ QUIESCE_TERM int32 = 1
+ QUIESCE_FORCE int32 = 2
+ QUIESCE_QUERY int32 = 3
+ QUIESCE_FREEZE int32 = 4
+ QUIESCE_UNFREEZE int32 = 5
+ FREEZE_THIS_THREAD int32 = 6
+ FREEZE_EXIT int32 = 8
+ QUIESCE_SRB int32 = 9
+)
+
+type Pgtha struct {
+ Pid uint32 // 0
+ Tid0 uint32 // 4
+ Tid1 uint32
+ Accesspid byte // C
+ Accesstid byte // D
+ Accessasid uint16 // E
+ Loginname [8]byte // 10
+ Flag1 byte // 18
+ Flag1b2 byte // 19
+}
+
+type Bpxystat_t struct { // DSECT BPXYSTAT
+ St_id [4]uint8 // 0
+ St_length uint16 // 0x4
+ St_version uint16 // 0x6
+ St_mode uint32 // 0x8
+ St_ino uint32 // 0xc
+ St_dev uint32 // 0x10
+ St_nlink uint32 // 0x14
+ St_uid uint32 // 0x18
+ St_gid uint32 // 0x1c
+ St_size uint64 // 0x20
+ St_atime uint32 // 0x28
+ St_mtime uint32 // 0x2c
+ St_ctime uint32 // 0x30
+ St_rdev uint32 // 0x34
+ St_auditoraudit uint32 // 0x38
+ St_useraudit uint32 // 0x3c
+ St_blksize uint32 // 0x40
+ St_createtime uint32 // 0x44
+ St_auditid [4]uint32 // 0x48
+ St_res01 uint32 // 0x58
+ Ft_ccsid uint16 // 0x5c
+ Ft_flags uint16 // 0x5e
+ St_res01a [2]uint32 // 0x60
+ St_res02 uint32 // 0x68
+ St_blocks uint32 // 0x6c
+ St_opaque [3]uint8 // 0x70
+ St_visible uint8 // 0x73
+ St_reftime uint32 // 0x74
+ St_fid uint64 // 0x78
+ St_filefmt uint8 // 0x80
+ St_fspflag2 uint8 // 0x81
+ St_res03 [2]uint8 // 0x82
+ St_ctimemsec uint32 // 0x84
+ St_seclabel [8]uint8 // 0x88
+ St_res04 [4]uint8 // 0x90
+ // end of version 1
+ _ uint32 // 0x94
+ St_atime64 uint64 // 0x98
+ St_mtime64 uint64 // 0xa0
+ St_ctime64 uint64 // 0xa8
+ St_createtime64 uint64 // 0xb0
+ St_reftime64 uint64 // 0xb8
+ _ uint64 // 0xc0
+ St_res05 [16]uint8 // 0xc8
+ // end of version 2
+}
+
+type BpxFilestatus struct {
+ Oflag1 byte
+ Oflag2 byte
+ Oflag3 byte
+ Oflag4 byte
+}
+
+type BpxMode struct {
+ Ftype byte
+ Mode1 byte
+ Mode2 byte
+ Mode3 byte
+}
+
+// Thr attribute structure for extended attributes
+type Bpxyatt_t struct { // DSECT BPXYATT
+ Att_id [4]uint8
+ Att_version uint16
+ Att_res01 [2]uint8
+ Att_setflags1 uint8
+ Att_setflags2 uint8
+ Att_setflags3 uint8
+ Att_setflags4 uint8
+ Att_mode uint32
+ Att_uid uint32
+ Att_gid uint32
+ Att_opaquemask [3]uint8
+ Att_visblmaskres uint8
+ Att_opaque [3]uint8
+ Att_visibleres uint8
+ Att_size_h uint32
+ Att_size_l uint32
+ Att_atime uint32
+ Att_mtime uint32
+ Att_auditoraudit uint32
+ Att_useraudit uint32
+ Att_ctime uint32
+ Att_reftime uint32
+ // end of version 1
+ Att_filefmt uint8
+ Att_res02 [3]uint8
+ Att_filetag uint32
+ Att_res03 [8]uint8
+ // end of version 2
+ Att_atime64 uint64
+ Att_mtime64 uint64
+ Att_ctime64 uint64
+ Att_reftime64 uint64
+ Att_seclabel [8]uint8
+ Att_ver3res02 [8]uint8
+ // end of version 3
+}
+
+func BpxOpen(name string, options *BpxFilestatus, mode *BpxMode) (rv int32, rc int32, rn int32) {
+ if len(name) < 1024 {
+ var namebuf [1024]byte
+ sz := int32(copy(namebuf[:], name))
+ A2e(namebuf[:sz])
+ var parms [7]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sz)
+ parms[1] = unsafe.Pointer(&namebuf[0])
+ parms[2] = unsafe.Pointer(options)
+ parms[3] = unsafe.Pointer(mode)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4OPN)
+ return rv, rc, rn
+ }
+ return -1, -1, -1
+}
+
+func BpxClose(fd int32) (rv int32, rc int32, rn int32) {
+ var parms [4]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&fd)
+ parms[1] = unsafe.Pointer(&rv)
+ parms[2] = unsafe.Pointer(&rc)
+ parms[3] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4CLO)
+ return rv, rc, rn
+}
+
+func BpxFileFStat(fd int32, st *Bpxystat_t) (rv int32, rc int32, rn int32) {
+ st.St_id = [4]uint8{0xe2, 0xe3, 0xc1, 0xe3}
+ st.St_version = 2
+ stat_sz := uint32(unsafe.Sizeof(*st))
+ var parms [6]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&fd)
+ parms[1] = unsafe.Pointer(&stat_sz)
+ parms[2] = unsafe.Pointer(st)
+ parms[3] = unsafe.Pointer(&rv)
+ parms[4] = unsafe.Pointer(&rc)
+ parms[5] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4FST)
+ return rv, rc, rn
+}
+
+func BpxFileStat(name string, st *Bpxystat_t) (rv int32, rc int32, rn int32) {
+ if len(name) < 1024 {
+ var namebuf [1024]byte
+ sz := int32(copy(namebuf[:], name))
+ A2e(namebuf[:sz])
+ st.St_id = [4]uint8{0xe2, 0xe3, 0xc1, 0xe3}
+ st.St_version = 2
+ stat_sz := uint32(unsafe.Sizeof(*st))
+ var parms [7]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sz)
+ parms[1] = unsafe.Pointer(&namebuf[0])
+ parms[2] = unsafe.Pointer(&stat_sz)
+ parms[3] = unsafe.Pointer(st)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4STA)
+ return rv, rc, rn
+ }
+ return -1, -1, -1
+}
+
+func BpxFileLStat(name string, st *Bpxystat_t) (rv int32, rc int32, rn int32) {
+ if len(name) < 1024 {
+ var namebuf [1024]byte
+ sz := int32(copy(namebuf[:], name))
+ A2e(namebuf[:sz])
+ st.St_id = [4]uint8{0xe2, 0xe3, 0xc1, 0xe3}
+ st.St_version = 2
+ stat_sz := uint32(unsafe.Sizeof(*st))
+ var parms [7]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sz)
+ parms[1] = unsafe.Pointer(&namebuf[0])
+ parms[2] = unsafe.Pointer(&stat_sz)
+ parms[3] = unsafe.Pointer(st)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4LST)
+ return rv, rc, rn
+ }
+ return -1, -1, -1
+}
+
+func BpxChattr(path string, attr *Bpxyatt_t) (rv int32, rc int32, rn int32) {
+ if len(path) >= 1024 {
+ return -1, -1, -1
+ }
+ var namebuf [1024]byte
+ sz := int32(copy(namebuf[:], path))
+ A2e(namebuf[:sz])
+ attr_sz := uint32(unsafe.Sizeof(*attr))
+ var parms [7]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sz)
+ parms[1] = unsafe.Pointer(&namebuf[0])
+ parms[2] = unsafe.Pointer(&attr_sz)
+ parms[3] = unsafe.Pointer(attr)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4CHR)
+ return rv, rc, rn
+}
+
+func BpxLchattr(path string, attr *Bpxyatt_t) (rv int32, rc int32, rn int32) {
+ if len(path) >= 1024 {
+ return -1, -1, -1
+ }
+ var namebuf [1024]byte
+ sz := int32(copy(namebuf[:], path))
+ A2e(namebuf[:sz])
+ attr_sz := uint32(unsafe.Sizeof(*attr))
+ var parms [7]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sz)
+ parms[1] = unsafe.Pointer(&namebuf[0])
+ parms[2] = unsafe.Pointer(&attr_sz)
+ parms[3] = unsafe.Pointer(attr)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4LCR)
+ return rv, rc, rn
+}
+
+func BpxFchattr(fd int32, attr *Bpxyatt_t) (rv int32, rc int32, rn int32) {
+ attr_sz := uint32(unsafe.Sizeof(*attr))
+ var parms [6]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&fd)
+ parms[1] = unsafe.Pointer(&attr_sz)
+ parms[2] = unsafe.Pointer(attr)
+ parms[3] = unsafe.Pointer(&rv)
+ parms[4] = unsafe.Pointer(&rc)
+ parms[5] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4FCR)
+ return rv, rc, rn
+}
+
+func BpxCondTimedWait(sec uint32, nsec uint32, events uint32, secrem *uint32, nsecrem *uint32) (rv int32, rc int32, rn int32) {
+ var parms [8]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&sec)
+ parms[1] = unsafe.Pointer(&nsec)
+ parms[2] = unsafe.Pointer(&events)
+ parms[3] = unsafe.Pointer(secrem)
+ parms[4] = unsafe.Pointer(nsecrem)
+ parms[5] = unsafe.Pointer(&rv)
+ parms[6] = unsafe.Pointer(&rc)
+ parms[7] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4CTW)
+ return rv, rc, rn
+}
+func BpxGetthent(in *Pgtha, outlen *uint32, out unsafe.Pointer) (rv int32, rc int32, rn int32) {
+ var parms [7]unsafe.Pointer
+ inlen := uint32(26) // nothing else will work. Go says Pgtha is 28-byte because of alignment, but Pgtha is "packed" and must be 26-byte
+ parms[0] = unsafe.Pointer(&inlen)
+ parms[1] = unsafe.Pointer(&in)
+ parms[2] = unsafe.Pointer(outlen)
+ parms[3] = unsafe.Pointer(&out)
+ parms[4] = unsafe.Pointer(&rv)
+ parms[5] = unsafe.Pointer(&rc)
+ parms[6] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4GTH)
+ return rv, rc, rn
+}
+func ZosJobname() (jobname string, err error) {
+ var pgtha Pgtha
+ pgtha.Pid = uint32(Getpid())
+ pgtha.Accesspid = PGTHA_CURRENT
+ pgtha.Flag1 = PGTHA_PROCESS
+ var out [256]byte
+ var outlen uint32
+ outlen = 256
+ rv, rc, rn := BpxGetthent(&pgtha, &outlen, unsafe.Pointer(&out[0]))
+ if rv == 0 {
+ gthc := []byte{0x87, 0xa3, 0x88, 0x83} // 'gthc' in ebcdic
+ ix := bytes.Index(out[:], gthc)
+ if ix == -1 {
+ err = fmt.Errorf("BPX4GTH: gthc return data not found")
+ return
+ }
+ jn := out[ix+80 : ix+88] // we didn't declare Pgthc, but jobname is 8-byte at offset 80
+ E2a(jn)
+ jobname = string(bytes.TrimRight(jn, " "))
+
+ } else {
+ err = fmt.Errorf("BPX4GTH: rc=%d errno=%d reason=code=0x%x", rv, rc, rn)
+ }
+ return
+}
+func Bpx4ptq(code int32, data string) (rv int32, rc int32, rn int32) {
+ var userdata [8]byte
+ var parms [5]unsafe.Pointer
+ copy(userdata[:], data+" ")
+ A2e(userdata[:])
+ parms[0] = unsafe.Pointer(&code)
+ parms[1] = unsafe.Pointer(&userdata[0])
+ parms[2] = unsafe.Pointer(&rv)
+ parms[3] = unsafe.Pointer(&rc)
+ parms[4] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4PTQ)
+ return rv, rc, rn
+}
+
+const (
+ PT_TRACE_ME = 0 // Debug this process
+ PT_READ_I = 1 // Read a full word
+ PT_READ_D = 2 // Read a full word
+ PT_READ_U = 3 // Read control info
+ PT_WRITE_I = 4 //Write a full word
+ PT_WRITE_D = 5 //Write a full word
+ PT_CONTINUE = 7 //Continue the process
+ PT_KILL = 8 //Terminate the process
+ PT_READ_GPR = 11 // Read GPR, CR, PSW
+ PT_READ_FPR = 12 // Read FPR
+ PT_READ_VR = 13 // Read VR
+ PT_WRITE_GPR = 14 // Write GPR, CR, PSW
+ PT_WRITE_FPR = 15 // Write FPR
+ PT_WRITE_VR = 16 // Write VR
+ PT_READ_BLOCK = 17 // Read storage
+ PT_WRITE_BLOCK = 19 // Write storage
+ PT_READ_GPRH = 20 // Read GPRH
+ PT_WRITE_GPRH = 21 // Write GPRH
+ PT_REGHSET = 22 // Read all GPRHs
+ PT_ATTACH = 30 // Attach to a process
+ PT_DETACH = 31 // Detach from a process
+ PT_REGSET = 32 // Read all GPRs
+ PT_REATTACH = 33 // Reattach to a process
+ PT_LDINFO = 34 // Read loader info
+ PT_MULTI = 35 // Multi process mode
+ PT_LD64INFO = 36 // RMODE64 Info Area
+ PT_BLOCKREQ = 40 // Block request
+ PT_THREAD_INFO = 60 // Read thread info
+ PT_THREAD_MODIFY = 61
+ PT_THREAD_READ_FOCUS = 62
+ PT_THREAD_WRITE_FOCUS = 63
+ PT_THREAD_HOLD = 64
+ PT_THREAD_SIGNAL = 65
+ PT_EXPLAIN = 66
+ PT_EVENTS = 67
+ PT_THREAD_INFO_EXTENDED = 68
+ PT_REATTACH2 = 71
+ PT_CAPTURE = 72
+ PT_UNCAPTURE = 73
+ PT_GET_THREAD_TCB = 74
+ PT_GET_ALET = 75
+ PT_SWAPIN = 76
+ PT_EXTENDED_EVENT = 98
+ PT_RECOVER = 99 // Debug a program check
+ PT_GPR0 = 0 // General purpose register 0
+ PT_GPR1 = 1 // General purpose register 1
+ PT_GPR2 = 2 // General purpose register 2
+ PT_GPR3 = 3 // General purpose register 3
+ PT_GPR4 = 4 // General purpose register 4
+ PT_GPR5 = 5 // General purpose register 5
+ PT_GPR6 = 6 // General purpose register 6
+ PT_GPR7 = 7 // General purpose register 7
+ PT_GPR8 = 8 // General purpose register 8
+ PT_GPR9 = 9 // General purpose register 9
+ PT_GPR10 = 10 // General purpose register 10
+ PT_GPR11 = 11 // General purpose register 11
+ PT_GPR12 = 12 // General purpose register 12
+ PT_GPR13 = 13 // General purpose register 13
+ PT_GPR14 = 14 // General purpose register 14
+ PT_GPR15 = 15 // General purpose register 15
+ PT_FPR0 = 16 // Floating point register 0
+ PT_FPR1 = 17 // Floating point register 1
+ PT_FPR2 = 18 // Floating point register 2
+ PT_FPR3 = 19 // Floating point register 3
+ PT_FPR4 = 20 // Floating point register 4
+ PT_FPR5 = 21 // Floating point register 5
+ PT_FPR6 = 22 // Floating point register 6
+ PT_FPR7 = 23 // Floating point register 7
+ PT_FPR8 = 24 // Floating point register 8
+ PT_FPR9 = 25 // Floating point register 9
+ PT_FPR10 = 26 // Floating point register 10
+ PT_FPR11 = 27 // Floating point register 11
+ PT_FPR12 = 28 // Floating point register 12
+ PT_FPR13 = 29 // Floating point register 13
+ PT_FPR14 = 30 // Floating point register 14
+ PT_FPR15 = 31 // Floating point register 15
+ PT_FPC = 32 // Floating point control register
+ PT_PSW = 40 // PSW
+ PT_PSW0 = 40 // Left half of the PSW
+ PT_PSW1 = 41 // Right half of the PSW
+ PT_CR0 = 42 // Control register 0
+ PT_CR1 = 43 // Control register 1
+ PT_CR2 = 44 // Control register 2
+ PT_CR3 = 45 // Control register 3
+ PT_CR4 = 46 // Control register 4
+ PT_CR5 = 47 // Control register 5
+ PT_CR6 = 48 // Control register 6
+ PT_CR7 = 49 // Control register 7
+ PT_CR8 = 50 // Control register 8
+ PT_CR9 = 51 // Control register 9
+ PT_CR10 = 52 // Control register 10
+ PT_CR11 = 53 // Control register 11
+ PT_CR12 = 54 // Control register 12
+ PT_CR13 = 55 // Control register 13
+ PT_CR14 = 56 // Control register 14
+ PT_CR15 = 57 // Control register 15
+ PT_GPRH0 = 58 // GP High register 0
+ PT_GPRH1 = 59 // GP High register 1
+ PT_GPRH2 = 60 // GP High register 2
+ PT_GPRH3 = 61 // GP High register 3
+ PT_GPRH4 = 62 // GP High register 4
+ PT_GPRH5 = 63 // GP High register 5
+ PT_GPRH6 = 64 // GP High register 6
+ PT_GPRH7 = 65 // GP High register 7
+ PT_GPRH8 = 66 // GP High register 8
+ PT_GPRH9 = 67 // GP High register 9
+ PT_GPRH10 = 68 // GP High register 10
+ PT_GPRH11 = 69 // GP High register 11
+ PT_GPRH12 = 70 // GP High register 12
+ PT_GPRH13 = 71 // GP High register 13
+ PT_GPRH14 = 72 // GP High register 14
+ PT_GPRH15 = 73 // GP High register 15
+ PT_VR0 = 74 // Vector register 0
+ PT_VR1 = 75 // Vector register 1
+ PT_VR2 = 76 // Vector register 2
+ PT_VR3 = 77 // Vector register 3
+ PT_VR4 = 78 // Vector register 4
+ PT_VR5 = 79 // Vector register 5
+ PT_VR6 = 80 // Vector register 6
+ PT_VR7 = 81 // Vector register 7
+ PT_VR8 = 82 // Vector register 8
+ PT_VR9 = 83 // Vector register 9
+ PT_VR10 = 84 // Vector register 10
+ PT_VR11 = 85 // Vector register 11
+ PT_VR12 = 86 // Vector register 12
+ PT_VR13 = 87 // Vector register 13
+ PT_VR14 = 88 // Vector register 14
+ PT_VR15 = 89 // Vector register 15
+ PT_VR16 = 90 // Vector register 16
+ PT_VR17 = 91 // Vector register 17
+ PT_VR18 = 92 // Vector register 18
+ PT_VR19 = 93 // Vector register 19
+ PT_VR20 = 94 // Vector register 20
+ PT_VR21 = 95 // Vector register 21
+ PT_VR22 = 96 // Vector register 22
+ PT_VR23 = 97 // Vector register 23
+ PT_VR24 = 98 // Vector register 24
+ PT_VR25 = 99 // Vector register 25
+ PT_VR26 = 100 // Vector register 26
+ PT_VR27 = 101 // Vector register 27
+ PT_VR28 = 102 // Vector register 28
+ PT_VR29 = 103 // Vector register 29
+ PT_VR30 = 104 // Vector register 30
+ PT_VR31 = 105 // Vector register 31
+ PT_PSWG = 106 // PSWG
+ PT_PSWG0 = 106 // Bytes 0-3
+ PT_PSWG1 = 107 // Bytes 4-7
+ PT_PSWG2 = 108 // Bytes 8-11 (IA high word)
+ PT_PSWG3 = 109 // Bytes 12-15 (IA low word)
+)
+
+func Bpx4ptr(request int32, pid int32, addr unsafe.Pointer, data unsafe.Pointer, buffer unsafe.Pointer) (rv int32, rc int32, rn int32) {
+ var parms [8]unsafe.Pointer
+ parms[0] = unsafe.Pointer(&request)
+ parms[1] = unsafe.Pointer(&pid)
+ parms[2] = unsafe.Pointer(&addr)
+ parms[3] = unsafe.Pointer(&data)
+ parms[4] = unsafe.Pointer(&buffer)
+ parms[5] = unsafe.Pointer(&rv)
+ parms[6] = unsafe.Pointer(&rc)
+ parms[7] = unsafe.Pointer(&rn)
+ bpxcall(parms[:], BPX4PTR)
+ return rv, rc, rn
+}
+
+func copyU8(val uint8, dest []uint8) int {
+ if len(dest) < 1 {
+ return 0
+ }
+ dest[0] = val
+ return 1
+}
+
+func copyU8Arr(src, dest []uint8) int {
+ if len(dest) < len(src) {
+ return 0
+ }
+ for i, v := range src {
+ dest[i] = v
+ }
+ return len(src)
+}
+
+func copyU16(val uint16, dest []uint16) int {
+ if len(dest) < 1 {
+ return 0
+ }
+ dest[0] = val
+ return 1
+}
+
+func copyU32(val uint32, dest []uint32) int {
+ if len(dest) < 1 {
+ return 0
+ }
+ dest[0] = val
+ return 1
+}
+
+func copyU32Arr(src, dest []uint32) int {
+ if len(dest) < len(src) {
+ return 0
+ }
+ for i, v := range src {
+ dest[i] = v
+ }
+ return len(src)
+}
+
+func copyU64(val uint64, dest []uint64) int {
+ if len(dest) < 1 {
+ return 0
+ }
+ dest[0] = val
+ return 1
+}
diff --git a/vendor/golang.org/x/sys/unix/bpxsvc_zos.s b/vendor/golang.org/x/sys/unix/bpxsvc_zos.s
new file mode 100644
index 0000000..4bd4a17
--- /dev/null
+++ b/vendor/golang.org/x/sys/unix/bpxsvc_zos.s
@@ -0,0 +1,192 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+#include "go_asm.h"
+#include "textflag.h"
+
+// function to call USS assembly language services
+//
+// doc: https://www.ibm.com/support/knowledgecenter/en/SSLTBW_3.1.0/com.ibm.zos.v3r1.bpxb100/bit64env.htm
+//
+// arg1 unsafe.Pointer array that ressembles an OS PLIST
+//
+// arg2 function offset as in
+// doc: https://www.ibm.com/support/knowledgecenter/en/SSLTBW_3.1.0/com.ibm.zos.v3r1.bpxb100/bpx2cr_List_of_offsets.htm
+//
+// func bpxcall(plist []unsafe.Pointer, bpx_offset int64)
+
+TEXT ·bpxcall(SB), NOSPLIT|NOFRAME, $0
+ MOVD plist_base+0(FP), R1 // r1 points to plist
+ MOVD bpx_offset+24(FP), R2 // r2 offset to BPX vector table
+ MOVD R14, R7 // save r14
+ MOVD R15, R8 // save r15
+ MOVWZ 16(R0), R9
+ MOVWZ 544(R9), R9
+ MOVWZ 24(R9), R9 // call vector in r9
+ ADD R2, R9 // add offset to vector table
+ MOVWZ (R9), R9 // r9 points to entry point
+ BYTE $0x0D // BL R14,R9 --> basr r14,r9
+ BYTE $0xE9 // clobbers 0,1,14,15
+ MOVD R8, R15 // restore 15
+ JMP R7 // return via saved return address
+
+// func A2e(arr [] byte)
+// code page conversion from 819 to 1047
+TEXT ·A2e(SB), NOSPLIT|NOFRAME, $0
+ MOVD arg_base+0(FP), R2 // pointer to arry of characters
+ MOVD arg_len+8(FP), R3 // count
+ XOR R0, R0
+ XOR R1, R1
+ BYTE $0xA7; BYTE $0x15; BYTE $0x00; BYTE $0x82 // BRAS 1,(2+(256/2))
+
+ // ASCII -> EBCDIC conversion table:
+ BYTE $0x00; BYTE $0x01; BYTE $0x02; BYTE $0x03
+ BYTE $0x37; BYTE $0x2d; BYTE $0x2e; BYTE $0x2f
+ BYTE $0x16; BYTE $0x05; BYTE $0x15; BYTE $0x0b
+ BYTE $0x0c; BYTE $0x0d; BYTE $0x0e; BYTE $0x0f
+ BYTE $0x10; BYTE $0x11; BYTE $0x12; BYTE $0x13
+ BYTE $0x3c; BYTE $0x3d; BYTE $0x32; BYTE $0x26
+ BYTE $0x18; BYTE $0x19; BYTE $0x3f; BYTE $0x27
+ BYTE $0x1c; BYTE $0x1d; BYTE $0x1e; BYTE $0x1f
+ BYTE $0x40; BYTE $0x5a; BYTE $0x7f; BYTE $0x7b
+ BYTE $0x5b; BYTE $0x6c; BYTE $0x50; BYTE $0x7d
+ BYTE $0x4d; BYTE $0x5d; BYTE $0x5c; BYTE $0x4e
+ BYTE $0x6b; BYTE $0x60; BYTE $0x4b; BYTE $0x61
+ BYTE $0xf0; BYTE $0xf1; BYTE $0xf2; BYTE $0xf3
+ BYTE $0xf4; BYTE $0xf5; BYTE $0xf6; BYTE $0xf7
+ BYTE $0xf8; BYTE $0xf9; BYTE $0x7a; BYTE $0x5e
+ BYTE $0x4c; BYTE $0x7e; BYTE $0x6e; BYTE $0x6f
+ BYTE $0x7c; BYTE $0xc1; BYTE $0xc2; BYTE $0xc3
+ BYTE $0xc4; BYTE $0xc5; BYTE $0xc6; BYTE $0xc7
+ BYTE $0xc8; BYTE $0xc9; BYTE $0xd1; BYTE $0xd2
+ BYTE $0xd3; BYTE $0xd4; BYTE $0xd5; BYTE $0xd6
+ BYTE $0xd7; BYTE $0xd8; BYTE $0xd9; BYTE $0xe2
+ BYTE $0xe3; BYTE $0xe4; BYTE $0xe5; BYTE $0xe6
+ BYTE $0xe7; BYTE $0xe8; BYTE $0xe9; BYTE $0xad
+ BYTE $0xe0; BYTE $0xbd; BYTE $0x5f; BYTE $0x6d
+ BYTE $0x79; BYTE $0x81; BYTE $0x82; BYTE $0x83
+ BYTE $0x84; BYTE $0x85; BYTE $0x86; BYTE $0x87
+ BYTE $0x88; BYTE $0x89; BYTE $0x91; BYTE $0x92
+ BYTE $0x93; BYTE $0x94; BYTE $0x95; BYTE $0x96
+ BYTE $0x97; BYTE $0x98; BYTE $0x99; BYTE $0xa2
+ BYTE $0xa3; BYTE $0xa4; BYTE $0xa5; BYTE $0xa6
+ BYTE $0xa7; BYTE $0xa8; BYTE $0xa9; BYTE $0xc0
+ BYTE $0x4f; BYTE $0xd0; BYTE $0xa1; BYTE $0x07
+ BYTE $0x20; BYTE $0x21; BYTE $0x22; BYTE $0x23
+ BYTE $0x24; BYTE $0x25; BYTE $0x06; BYTE $0x17
+ BYTE $0x28; BYTE $0x29; BYTE $0x2a; BYTE $0x2b
+ BYTE $0x2c; BYTE $0x09; BYTE $0x0a; BYTE $0x1b
+ BYTE $0x30; BYTE $0x31; BYTE $0x1a; BYTE $0x33
+ BYTE $0x34; BYTE $0x35; BYTE $0x36; BYTE $0x08
+ BYTE $0x38; BYTE $0x39; BYTE $0x3a; BYTE $0x3b
+ BYTE $0x04; BYTE $0x14; BYTE $0x3e; BYTE $0xff
+ BYTE $0x41; BYTE $0xaa; BYTE $0x4a; BYTE $0xb1
+ BYTE $0x9f; BYTE $0xb2; BYTE $0x6a; BYTE $0xb5
+ BYTE $0xbb; BYTE $0xb4; BYTE $0x9a; BYTE $0x8a
+ BYTE $0xb0; BYTE $0xca; BYTE $0xaf; BYTE $0xbc
+ BYTE $0x90; BYTE $0x8f; BYTE $0xea; BYTE $0xfa
+ BYTE $0xbe; BYTE $0xa0; BYTE $0xb6; BYTE $0xb3
+ BYTE $0x9d; BYTE $0xda; BYTE $0x9b; BYTE $0x8b
+ BYTE $0xb7; BYTE $0xb8; BYTE $0xb9; BYTE $0xab
+ BYTE $0x64; BYTE $0x65; BYTE $0x62; BYTE $0x66
+ BYTE $0x63; BYTE $0x67; BYTE $0x9e; BYTE $0x68
+ BYTE $0x74; BYTE $0x71; BYTE $0x72; BYTE $0x73
+ BYTE $0x78; BYTE $0x75; BYTE $0x76; BYTE $0x77
+ BYTE $0xac; BYTE $0x69; BYTE $0xed; BYTE $0xee
+ BYTE $0xeb; BYTE $0xef; BYTE $0xec; BYTE $0xbf
+ BYTE $0x80; BYTE $0xfd; BYTE $0xfe; BYTE $0xfb
+ BYTE $0xfc; BYTE $0xba; BYTE $0xae; BYTE $0x59
+ BYTE $0x44; BYTE $0x45; BYTE $0x42; BYTE $0x46
+ BYTE $0x43; BYTE $0x47; BYTE $0x9c; BYTE $0x48
+ BYTE $0x54; BYTE $0x51; BYTE $0x52; BYTE $0x53
+ BYTE $0x58; BYTE $0x55; BYTE $0x56; BYTE $0x57
+ BYTE $0x8c; BYTE $0x49; BYTE $0xcd; BYTE $0xce
+ BYTE $0xcb; BYTE $0xcf; BYTE $0xcc; BYTE $0xe1
+ BYTE $0x70; BYTE $0xdd; BYTE $0xde; BYTE $0xdb
+ BYTE $0xdc; BYTE $0x8d; BYTE $0x8e; BYTE $0xdf
+
+retry:
+ WORD $0xB9931022 // TROO 2,2,b'0001'
+ BVS retry
+ RET
+
+// func e2a(arr [] byte)
+// code page conversion from 1047 to 819
+TEXT ·E2a(SB), NOSPLIT|NOFRAME, $0
+ MOVD arg_base+0(FP), R2 // pointer to arry of characters
+ MOVD arg_len+8(FP), R3 // count
+ XOR R0, R0
+ XOR R1, R1
+ BYTE $0xA7; BYTE $0x15; BYTE $0x00; BYTE $0x82 // BRAS 1,(2+(256/2))
+
+ // EBCDIC -> ASCII conversion table:
+ BYTE $0x00; BYTE $0x01; BYTE $0x02; BYTE $0x03
+ BYTE $0x9c; BYTE $0x09; BYTE $0x86; BYTE $0x7f
+ BYTE $0x97; BYTE $0x8d; BYTE $0x8e; BYTE $0x0b
+ BYTE $0x0c; BYTE $0x0d; BYTE $0x0e; BYTE $0x0f
+ BYTE $0x10; BYTE $0x11; BYTE $0x12; BYTE $0x13
+ BYTE $0x9d; BYTE $0x0a; BYTE $0x08; BYTE $0x87
+ BYTE $0x18; BYTE $0x19; BYTE $0x92; BYTE $0x8f
+ BYTE $0x1c; BYTE $0x1d; BYTE $0x1e; BYTE $0x1f
+ BYTE $0x80; BYTE $0x81; BYTE $0x82; BYTE $0x83
+ BYTE $0x84; BYTE $0x85; BYTE $0x17; BYTE $0x1b
+ BYTE $0x88; BYTE $0x89; BYTE $0x8a; BYTE $0x8b
+ BYTE $0x8c; BYTE $0x05; BYTE $0x06; BYTE $0x07
+ BYTE $0x90; BYTE $0x91; BYTE $0x16; BYTE $0x93
+ BYTE $0x94; BYTE $0x95; BYTE $0x96; BYTE $0x04
+ BYTE $0x98; BYTE $0x99; BYTE $0x9a; BYTE $0x9b
+ BYTE $0x14; BYTE $0x15; BYTE $0x9e; BYTE $0x1a
+ BYTE $0x20; BYTE $0xa0; BYTE $0xe2; BYTE $0xe4
+ BYTE $0xe0; BYTE $0xe1; BYTE $0xe3; BYTE $0xe5
+ BYTE $0xe7; BYTE $0xf1; BYTE $0xa2; BYTE $0x2e
+ BYTE $0x3c; BYTE $0x28; BYTE $0x2b; BYTE $0x7c
+ BYTE $0x26; BYTE $0xe9; BYTE $0xea; BYTE $0xeb
+ BYTE $0xe8; BYTE $0xed; BYTE $0xee; BYTE $0xef
+ BYTE $0xec; BYTE $0xdf; BYTE $0x21; BYTE $0x24
+ BYTE $0x2a; BYTE $0x29; BYTE $0x3b; BYTE $0x5e
+ BYTE $0x2d; BYTE $0x2f; BYTE $0xc2; BYTE $0xc4
+ BYTE $0xc0; BYTE $0xc1; BYTE $0xc3; BYTE $0xc5
+ BYTE $0xc7; BYTE $0xd1; BYTE $0xa6; BYTE $0x2c
+ BYTE $0x25; BYTE $0x5f; BYTE $0x3e; BYTE $0x3f
+ BYTE $0xf8; BYTE $0xc9; BYTE $0xca; BYTE $0xcb
+ BYTE $0xc8; BYTE $0xcd; BYTE $0xce; BYTE $0xcf
+ BYTE $0xcc; BYTE $0x60; BYTE $0x3a; BYTE $0x23
+ BYTE $0x40; BYTE $0x27; BYTE $0x3d; BYTE $0x22
+ BYTE $0xd8; BYTE $0x61; BYTE $0x62; BYTE $0x63
+ BYTE $0x64; BYTE $0x65; BYTE $0x66; BYTE $0x67
+ BYTE $0x68; BYTE $0x69; BYTE $0xab; BYTE $0xbb
+ BYTE $0xf0; BYTE $0xfd; BYTE $0xfe; BYTE $0xb1
+ BYTE $0xb0; BYTE $0x6a; BYTE $0x6b; BYTE $0x6c
+ BYTE $0x6d; BYTE $0x6e; BYTE $0x6f; BYTE $0x70
+ BYTE $0x71; BYTE $0x72; BYTE $0xaa; BYTE $0xba
+ BYTE $0xe6; BYTE $0xb8; BYTE $0xc6; BYTE $0xa4
+ BYTE $0xb5; BYTE $0x7e; BYTE $0x73; BYTE $0x74
+ BYTE $0x75; BYTE $0x76; BYTE $0x77; BYTE $0x78
+ BYTE $0x79; BYTE $0x7a; BYTE $0xa1; BYTE $0xbf
+ BYTE $0xd0; BYTE $0x5b; BYTE $0xde; BYTE $0xae
+ BYTE $0xac; BYTE $0xa3; BYTE $0xa5; BYTE $0xb7
+ BYTE $0xa9; BYTE $0xa7; BYTE $0xb6; BYTE $0xbc
+ BYTE $0xbd; BYTE $0xbe; BYTE $0xdd; BYTE $0xa8
+ BYTE $0xaf; BYTE $0x5d; BYTE $0xb4; BYTE $0xd7
+ BYTE $0x7b; BYTE $0x41; BYTE $0x42; BYTE $0x43
+ BYTE $0x44; BYTE $0x45; BYTE $0x46; BYTE $0x47
+ BYTE $0x48; BYTE $0x49; BYTE $0xad; BYTE $0xf4
+ BYTE $0xf6; BYTE $0xf2; BYTE $0xf3; BYTE $0xf5
+ BYTE $0x7d; BYTE $0x4a; BYTE $0x4b; BYTE $0x4c
+ BYTE $0x4d; BYTE $0x4e; BYTE $0x4f; BYTE $0x50
+ BYTE $0x51; BYTE $0x52; BYTE $0xb9; BYTE $0xfb
+ BYTE $0xfc; BYTE $0xf9; BYTE $0xfa; BYTE $0xff
+ BYTE $0x5c; BYTE $0xf7; BYTE $0x53; BYTE $0x54
+ BYTE $0x55; BYTE $0x56; BYTE $0x57; BYTE $0x58
+ BYTE $0x59; BYTE $0x5a; BYTE $0xb2; BYTE $0xd4
+ BYTE $0xd6; BYTE $0xd2; BYTE $0xd3; BYTE $0xd5
+ BYTE $0x30; BYTE $0x31; BYTE $0x32; BYTE $0x33
+ BYTE $0x34; BYTE $0x35; BYTE $0x36; BYTE $0x37
+ BYTE $0x38; BYTE $0x39; BYTE $0xb3; BYTE $0xdb
+ BYTE $0xdc; BYTE $0xd9; BYTE $0xda; BYTE $0x9f
+
+retry:
+ WORD $0xB9931022 // TROO 2,2,b'0001'
+ BVS retry
+ RET
diff --git a/vendor/golang.org/x/sys/unix/epoll_zos.go b/vendor/golang.org/x/sys/unix/epoll_zos.go
deleted file mode 100644
index 7753fdd..0000000
--- a/vendor/golang.org/x/sys/unix/epoll_zos.go
+++ /dev/null
@@ -1,220 +0,0 @@
-// Copyright 2020 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-//go:build zos && s390x
-
-package unix
-
-import (
- "sync"
-)
-
-// This file simulates epoll on z/OS using poll.
-
-// Analogous to epoll_event on Linux.
-// TODO(neeilan): Pad is because the Linux kernel expects a 96-bit struct. We never pass this to the kernel; remove?
-type EpollEvent struct {
- Events uint32
- Fd int32
- Pad int32
-}
-
-const (
- EPOLLERR = 0x8
- EPOLLHUP = 0x10
- EPOLLIN = 0x1
- EPOLLMSG = 0x400
- EPOLLOUT = 0x4
- EPOLLPRI = 0x2
- EPOLLRDBAND = 0x80
- EPOLLRDNORM = 0x40
- EPOLLWRBAND = 0x200
- EPOLLWRNORM = 0x100
- EPOLL_CTL_ADD = 0x1
- EPOLL_CTL_DEL = 0x2
- EPOLL_CTL_MOD = 0x3
- // The following constants are part of the epoll API, but represent
- // currently unsupported functionality on z/OS.
- // EPOLL_CLOEXEC = 0x80000
- // EPOLLET = 0x80000000
- // EPOLLONESHOT = 0x40000000
- // EPOLLRDHUP = 0x2000 // Typically used with edge-triggered notis
- // EPOLLEXCLUSIVE = 0x10000000 // Exclusive wake-up mode
- // EPOLLWAKEUP = 0x20000000 // Relies on Linux's BLOCK_SUSPEND capability
-)
-
-// TODO(neeilan): We can eliminate these epToPoll / pToEpoll calls by using identical mask values for POLL/EPOLL
-// constants where possible The lower 16 bits of epoll events (uint32) can fit any system poll event (int16).
-
-// epToPollEvt converts epoll event field to poll equivalent.
-// In epoll, Events is a 32-bit field, while poll uses 16 bits.
-func epToPollEvt(events uint32) int16 {
- var ep2p = map[uint32]int16{
- EPOLLIN: POLLIN,
- EPOLLOUT: POLLOUT,
- EPOLLHUP: POLLHUP,
- EPOLLPRI: POLLPRI,
- EPOLLERR: POLLERR,
- }
-
- var pollEvts int16 = 0
- for epEvt, pEvt := range ep2p {
- if (events & epEvt) != 0 {
- pollEvts |= pEvt
- }
- }
-
- return pollEvts
-}
-
-// pToEpollEvt converts 16 bit poll event bitfields to 32-bit epoll event fields.
-func pToEpollEvt(revents int16) uint32 {
- var p2ep = map[int16]uint32{
- POLLIN: EPOLLIN,
- POLLOUT: EPOLLOUT,
- POLLHUP: EPOLLHUP,
- POLLPRI: EPOLLPRI,
- POLLERR: EPOLLERR,
- }
-
- var epollEvts uint32 = 0
- for pEvt, epEvt := range p2ep {
- if (revents & pEvt) != 0 {
- epollEvts |= epEvt
- }
- }
-
- return epollEvts
-}
-
-// Per-process epoll implementation.
-type epollImpl struct {
- mu sync.Mutex
- epfd2ep map[int]*eventPoll
- nextEpfd int
-}
-
-// eventPoll holds a set of file descriptors being watched by the process. A process can have multiple epoll instances.
-// On Linux, this is an in-kernel data structure accessed through a fd.
-type eventPoll struct {
- mu sync.Mutex
- fds map[int]*EpollEvent
-}
-
-// epoll impl for this process.
-var impl epollImpl = epollImpl{
- epfd2ep: make(map[int]*eventPoll),
- nextEpfd: 0,
-}
-
-func (e *epollImpl) epollcreate(size int) (epfd int, err error) {
- e.mu.Lock()
- defer e.mu.Unlock()
- epfd = e.nextEpfd
- e.nextEpfd++
-
- e.epfd2ep[epfd] = &eventPoll{
- fds: make(map[int]*EpollEvent),
- }
- return epfd, nil
-}
-
-func (e *epollImpl) epollcreate1(flag int) (fd int, err error) {
- return e.epollcreate(4)
-}
-
-func (e *epollImpl) epollctl(epfd int, op int, fd int, event *EpollEvent) (err error) {
- e.mu.Lock()
- defer e.mu.Unlock()
-
- ep, ok := e.epfd2ep[epfd]
- if !ok {
-
- return EBADF
- }
-
- switch op {
- case EPOLL_CTL_ADD:
- // TODO(neeilan): When we make epfds and fds disjoint, detect epoll
- // loops here (instances watching each other) and return ELOOP.
- if _, ok := ep.fds[fd]; ok {
- return EEXIST
- }
- ep.fds[fd] = event
- case EPOLL_CTL_MOD:
- if _, ok := ep.fds[fd]; !ok {
- return ENOENT
- }
- ep.fds[fd] = event
- case EPOLL_CTL_DEL:
- if _, ok := ep.fds[fd]; !ok {
- return ENOENT
- }
- delete(ep.fds, fd)
-
- }
- return nil
-}
-
-// Must be called while holding ep.mu
-func (ep *eventPoll) getFds() []int {
- fds := make([]int, len(ep.fds))
- for fd := range ep.fds {
- fds = append(fds, fd)
- }
- return fds
-}
-
-func (e *epollImpl) epollwait(epfd int, events []EpollEvent, msec int) (n int, err error) {
- e.mu.Lock() // in [rare] case of concurrent epollcreate + epollwait
- ep, ok := e.epfd2ep[epfd]
-
- if !ok {
- e.mu.Unlock()
- return 0, EBADF
- }
-
- pollfds := make([]PollFd, 4)
- for fd, epollevt := range ep.fds {
- pollfds = append(pollfds, PollFd{Fd: int32(fd), Events: epToPollEvt(epollevt.Events)})
- }
- e.mu.Unlock()
-
- n, err = Poll(pollfds, msec)
- if err != nil {
- return n, err
- }
-
- i := 0
- for _, pFd := range pollfds {
- if pFd.Revents != 0 {
- events[i] = EpollEvent{Fd: pFd.Fd, Events: pToEpollEvt(pFd.Revents)}
- i++
- }
-
- if i == n {
- break
- }
- }
-
- return n, nil
-}
-
-func EpollCreate(size int) (fd int, err error) {
- return impl.epollcreate(size)
-}
-
-func EpollCreate1(flag int) (fd int, err error) {
- return impl.epollcreate1(flag)
-}
-
-func EpollCtl(epfd int, op int, fd int, event *EpollEvent) (err error) {
- return impl.epollctl(epfd, op, fd, event)
-}
-
-// Because EpollWait mutates events, the caller is expected to coordinate
-// concurrent access if calling with the same epfd from multiple goroutines.
-func EpollWait(epfd int, events []EpollEvent, msec int) (n int, err error) {
- return impl.epollwait(epfd, events, msec)
-}
diff --git a/vendor/golang.org/x/sys/unix/fstatfs_zos.go b/vendor/golang.org/x/sys/unix/fstatfs_zos.go
deleted file mode 100644
index c8bde60..0000000
--- a/vendor/golang.org/x/sys/unix/fstatfs_zos.go
+++ /dev/null
@@ -1,163 +0,0 @@
-// Copyright 2020 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-//go:build zos && s390x
-
-package unix
-
-import (
- "unsafe"
-)
-
-// This file simulates fstatfs on z/OS using fstatvfs and w_getmntent.
-
-func Fstatfs(fd int, stat *Statfs_t) (err error) {
- var stat_v Statvfs_t
- err = Fstatvfs(fd, &stat_v)
- if err == nil {
- // populate stat
- stat.Type = 0
- stat.Bsize = stat_v.Bsize
- stat.Blocks = stat_v.Blocks
- stat.Bfree = stat_v.Bfree
- stat.Bavail = stat_v.Bavail
- stat.Files = stat_v.Files
- stat.Ffree = stat_v.Ffree
- stat.Fsid = stat_v.Fsid
- stat.Namelen = stat_v.Namemax
- stat.Frsize = stat_v.Frsize
- stat.Flags = stat_v.Flag
- for passn := 0; passn < 5; passn++ {
- switch passn {
- case 0:
- err = tryGetmntent64(stat)
- break
- case 1:
- err = tryGetmntent128(stat)
- break
- case 2:
- err = tryGetmntent256(stat)
- break
- case 3:
- err = tryGetmntent512(stat)
- break
- case 4:
- err = tryGetmntent1024(stat)
- break
- default:
- break
- }
- //proceed to return if: err is nil (found), err is nonnil but not ERANGE (another error occurred)
- if err == nil || err != nil && err != ERANGE {
- break
- }
- }
- }
- return err
-}
-
-func tryGetmntent64(stat *Statfs_t) (err error) {
- var mnt_ent_buffer struct {
- header W_Mnth
- filesys_info [64]W_Mntent
- }
- var buffer_size int = int(unsafe.Sizeof(mnt_ent_buffer))
- fs_count, err := W_Getmntent((*byte)(unsafe.Pointer(&mnt_ent_buffer)), buffer_size)
- if err != nil {
- return err
- }
- err = ERANGE //return ERANGE if no match is found in this batch
- for i := 0; i < fs_count; i++ {
- if stat.Fsid == uint64(mnt_ent_buffer.filesys_info[i].Dev) {
- stat.Type = uint32(mnt_ent_buffer.filesys_info[i].Fstname[0])
- err = nil
- break
- }
- }
- return err
-}
-
-func tryGetmntent128(stat *Statfs_t) (err error) {
- var mnt_ent_buffer struct {
- header W_Mnth
- filesys_info [128]W_Mntent
- }
- var buffer_size int = int(unsafe.Sizeof(mnt_ent_buffer))
- fs_count, err := W_Getmntent((*byte)(unsafe.Pointer(&mnt_ent_buffer)), buffer_size)
- if err != nil {
- return err
- }
- err = ERANGE //return ERANGE if no match is found in this batch
- for i := 0; i < fs_count; i++ {
- if stat.Fsid == uint64(mnt_ent_buffer.filesys_info[i].Dev) {
- stat.Type = uint32(mnt_ent_buffer.filesys_info[i].Fstname[0])
- err = nil
- break
- }
- }
- return err
-}
-
-func tryGetmntent256(stat *Statfs_t) (err error) {
- var mnt_ent_buffer struct {
- header W_Mnth
- filesys_info [256]W_Mntent
- }
- var buffer_size int = int(unsafe.Sizeof(mnt_ent_buffer))
- fs_count, err := W_Getmntent((*byte)(unsafe.Pointer(&mnt_ent_buffer)), buffer_size)
- if err != nil {
- return err
- }
- err = ERANGE //return ERANGE if no match is found in this batch
- for i := 0; i < fs_count; i++ {
- if stat.Fsid == uint64(mnt_ent_buffer.filesys_info[i].Dev) {
- stat.Type = uint32(mnt_ent_buffer.filesys_info[i].Fstname[0])
- err = nil
- break
- }
- }
- return err
-}
-
-func tryGetmntent512(stat *Statfs_t) (err error) {
- var mnt_ent_buffer struct {
- header W_Mnth
- filesys_info [512]W_Mntent
- }
- var buffer_size int = int(unsafe.Sizeof(mnt_ent_buffer))
- fs_count, err := W_Getmntent((*byte)(unsafe.Pointer(&mnt_ent_buffer)), buffer_size)
- if err != nil {
- return err
- }
- err = ERANGE //return ERANGE if no match is found in this batch
- for i := 0; i < fs_count; i++ {
- if stat.Fsid == uint64(mnt_ent_buffer.filesys_info[i].Dev) {
- stat.Type = uint32(mnt_ent_buffer.filesys_info[i].Fstname[0])
- err = nil
- break
- }
- }
- return err
-}
-
-func tryGetmntent1024(stat *Statfs_t) (err error) {
- var mnt_ent_buffer struct {
- header W_Mnth
- filesys_info [1024]W_Mntent
- }
- var buffer_size int = int(unsafe.Sizeof(mnt_ent_buffer))
- fs_count, err := W_Getmntent((*byte)(unsafe.Pointer(&mnt_ent_buffer)), buffer_size)
- if err != nil {
- return err
- }
- err = ERANGE //return ERANGE if no match is found in this batch
- for i := 0; i < fs_count; i++ {
- if stat.Fsid == uint64(mnt_ent_buffer.filesys_info[i].Dev) {
- stat.Type = uint32(mnt_ent_buffer.filesys_info[i].Fstname[0])
- err = nil
- break
- }
- }
- return err
-}
diff --git a/vendor/golang.org/x/sys/unix/mkerrors.sh b/vendor/golang.org/x/sys/unix/mkerrors.sh
index 6202638..fdcaa97 100644
--- a/vendor/golang.org/x/sys/unix/mkerrors.sh
+++ b/vendor/golang.org/x/sys/unix/mkerrors.sh
@@ -248,6 +248,7 @@ struct ltchars {
#include