mirror of
https://github.com/datarhei/core.git
synced 2025-10-15 12:30:45 +08:00
Add v16.7.2
This commit is contained in:
Jan Stabenow
22
vendor/github.com/swaggo/swag/.gitignore
generated
vendored
Normal file
22
vendor/github.com/swaggo/swag/.gitignore
generated
vendored
Normal file
@@ -0,0 +1,22 @@
|
||||
dist
|
||||
testdata/simple*/docs
|
||||
testdata/quotes/docs
|
||||
testdata/quotes/quotes.so
|
||||
example/basic/docs/*
|
||||
example/celler/docs/*
|
||||
cover.out
|
||||
|
||||
|
||||
# Test binary, build with `go test -c`
|
||||
*.test
|
||||
|
||||
# Output of the go coverage tool, specifically when used with LiteIDE
|
||||
*.out
|
||||
.idea
|
||||
.vscode
|
||||
|
||||
# Etc
|
||||
.DS_Store
|
||||
|
||||
/swag
|
||||
/swag.exe
|
||||
31
vendor/github.com/swaggo/swag/.goreleaser.yml
generated
vendored
Normal file
31
vendor/github.com/swaggo/swag/.goreleaser.yml
generated
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
build:
|
||||
main: cmd/swag/main.go
|
||||
goos:
|
||||
- linux
|
||||
- darwin
|
||||
goarch:
|
||||
- amd64
|
||||
- arm64
|
||||
- 386
|
||||
ignore:
|
||||
- goos: darwin
|
||||
goarch: arm64
|
||||
archives:
|
||||
-
|
||||
replacements:
|
||||
darwin: Darwin
|
||||
linux: Linux
|
||||
windows: Windows
|
||||
386: i386
|
||||
amd64: x86_64
|
||||
arm64: aarch64
|
||||
checksum:
|
||||
name_template: 'checksums.txt'
|
||||
snapshot:
|
||||
name_template: "{{ .Tag }}-next"
|
||||
changelog:
|
||||
sort: asc
|
||||
filters:
|
||||
exclude:
|
||||
- '^docs:'
|
||||
- '^test:'
|
||||
46
vendor/github.com/swaggo/swag/CODE_OF_CONDUCT.md
generated
vendored
Normal file
46
vendor/github.com/swaggo/swag/CODE_OF_CONDUCT.md
generated
vendored
Normal file
@@ -0,0 +1,46 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
* Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or electronic address, without explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [gitter.im/swaggo/swag](https://gitter.im/swaggo/swag).The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
|
||||
|
||||
[homepage]: http://contributor-covenant.org
|
||||
[version]: http://contributor-covenant.org/version/1/4/
|
||||
16
vendor/github.com/swaggo/swag/CONTRIBUTING.md
generated
vendored
Normal file
16
vendor/github.com/swaggo/swag/CONTRIBUTING.md
generated
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
# Contributing
|
||||
|
||||
When contributing to this repository, please first discuss the change you wish to make via issue,
|
||||
email, or any other method with the owners of this repository before making a change.
|
||||
|
||||
Please note we have a code of conduct, please follow it in all your interactions with the project.
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Fork it
|
||||
2. Create your feature branch (`git checkout -b my-new-feature`)
|
||||
3. Commit your changes (`git commit -am 'Add some feature'`)
|
||||
4. Push to the branch (`git push origin my-new-feature`)
|
||||
5. Create new Pull Request
|
||||
|
||||
Please make an issue first if the change is likely to increase.
|
||||
28
vendor/github.com/swaggo/swag/Dockerfile
generated
vendored
Normal file
28
vendor/github.com/swaggo/swag/Dockerfile
generated
vendored
Normal file
@@ -0,0 +1,28 @@
|
||||
# Dockerfile References: https://docs.docker.com/engine/reference/builder/
|
||||
|
||||
# Start from the latest golang base image
|
||||
FROM golang:1.17-alpine as builder
|
||||
|
||||
# Set the Current Working Directory inside the container
|
||||
WORKDIR /app
|
||||
|
||||
# Copy go mod and sum files
|
||||
COPY go.mod go.sum ./
|
||||
|
||||
# Download all dependencies. Dependencies will be cached if the go.mod and go.sum files are not changed
|
||||
RUN go mod download
|
||||
|
||||
# Copy the source from the current directory to the Working Directory inside the container
|
||||
COPY . .
|
||||
|
||||
# Build the Go app
|
||||
RUN CGO_ENABLED=0 GOOS=linux go build -v -a -installsuffix cgo -o swag cmd/swag/main.go
|
||||
|
||||
|
||||
######## Start a new stage from scratch #######
|
||||
FROM scratch
|
||||
|
||||
WORKDIR /root/
|
||||
|
||||
# Copy the Pre-built binary file from the previous stage
|
||||
COPY --from=builder /app/swag .
|
||||
94
vendor/github.com/swaggo/swag/Makefile
generated
vendored
Normal file
94
vendor/github.com/swaggo/swag/Makefile
generated
vendored
Normal file
@@ -0,0 +1,94 @@
|
||||
GOCMD:=$(shell which go)
|
||||
GOLINT:=$(shell which golint)
|
||||
GOIMPORT:=$(shell which goimports)
|
||||
GOFMT:=$(shell which gofmt)
|
||||
GOBUILD:=$(GOCMD) build
|
||||
GOINSTALL:=$(GOCMD) install
|
||||
GOCLEAN:=$(GOCMD) clean
|
||||
GOTEST:=$(GOCMD) test
|
||||
GOGET:=$(GOCMD) get
|
||||
GOLIST:=$(GOCMD) list
|
||||
GOVET:=$(GOCMD) vet
|
||||
GOPATH:=$(shell $(GOCMD) env GOPATH)
|
||||
u := $(if $(update),-u)
|
||||
|
||||
BINARY_NAME:=swag
|
||||
PACKAGES:=$(shell $(GOLIST) github.com/swaggo/swag github.com/swaggo/swag/cmd/swag github.com/swaggo/swag/gen)
|
||||
GOFILES:=$(shell find . -name "*.go" -type f)
|
||||
|
||||
export GO111MODULE := on
|
||||
|
||||
all: test build
|
||||
|
||||
.PHONY: build
|
||||
build: deps
|
||||
$(GOBUILD) -o $(BINARY_NAME) ./cmd/swag
|
||||
|
||||
.PHONY: install
|
||||
install: deps
|
||||
$(GOINSTALL) ./cmd/swag
|
||||
|
||||
.PHONY: test
|
||||
test:
|
||||
echo "mode: count" > coverage.out
|
||||
for PKG in $(PACKAGES); do \
|
||||
$(GOCMD) test -v -covermode=count -coverprofile=profile.out $$PKG > tmp.out; \
|
||||
cat tmp.out; \
|
||||
if grep -q "^--- FAIL" tmp.out; then \
|
||||
rm tmp.out; \
|
||||
exit 1; \
|
||||
elif grep -q "build failed" tmp.out; then \
|
||||
rm tmp.out; \
|
||||
exit; \
|
||||
fi; \
|
||||
if [ -f profile.out ]; then \
|
||||
cat profile.out | grep -v "mode:" >> coverage.out; \
|
||||
rm profile.out; \
|
||||
fi; \
|
||||
done
|
||||
|
||||
.PHONY: clean
|
||||
clean:
|
||||
$(GOCLEAN)
|
||||
rm -f $(BINARY_NAME)
|
||||
|
||||
.PHONY: deps
|
||||
deps:
|
||||
$(GOGET) github.com/swaggo/cli
|
||||
$(GOGET) github.com/ghodss/yaml
|
||||
$(GOGET) github.com/KyleBanks/depth
|
||||
$(GOGET) github.com/go-openapi/jsonreference
|
||||
$(GOGET) github.com/go-openapi/spec
|
||||
$(GOGET) github.com/stretchr/testify/assert
|
||||
$(GOGET) golang.org/x/tools/go/loader
|
||||
|
||||
.PHONY: devel-deps
|
||||
devel-deps:
|
||||
GO111MODULE=off $(GOGET) -v -u \
|
||||
golang.org/x/lint/golint
|
||||
|
||||
.PHONY: lint
|
||||
lint: devel-deps
|
||||
for PKG in $(PACKAGES); do golint -set_exit_status $$PKG || exit 1; done;
|
||||
|
||||
.PHONY: vet
|
||||
vet: deps devel-deps
|
||||
$(GOVET) $(PACKAGES)
|
||||
|
||||
.PHONY: fmt
|
||||
fmt:
|
||||
$(GOFMT) -s -w $(GOFILES)
|
||||
|
||||
.PHONY: fmt-check
|
||||
fmt-check:
|
||||
@diff=$$($(GOFMT) -s -d $(GOFILES)); \
|
||||
if [ -n "$$diff" ]; then \
|
||||
echo "Please run 'make fmt' and commit the result:"; \
|
||||
echo "$${diff}"; \
|
||||
exit 1; \
|
||||
fi;
|
||||
|
||||
.PHONY: view-covered
|
||||
view-covered:
|
||||
$(GOTEST) -coverprofile=cover.out $(TARGET)
|
||||
$(GOCMD) tool cover -html=cover.out
|
||||
8
vendor/github.com/swaggo/swag/PULL_REQUEST_TEMPLATE.md
generated
vendored
Normal file
8
vendor/github.com/swaggo/swag/PULL_REQUEST_TEMPLATE.md
generated
vendored
Normal file
@@ -0,0 +1,8 @@
|
||||
**Describe the PR**
|
||||
e.g. add cool parser.
|
||||
|
||||
**Relation issue**
|
||||
e.g. https://github.com/swaggo/swag/pull/118/files
|
||||
|
||||
**Additional context**
|
||||
Add any other context about the problem here.
|
||||
870
vendor/github.com/swaggo/swag/README.md
generated
vendored
Normal file
870
vendor/github.com/swaggo/swag/README.md
generated
vendored
Normal file
@@ -0,0 +1,870 @@
|
||||
# swag
|
||||
|
||||
🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md)*
|
||||
|
||||
<img align="right" width="180px" src="https://raw.githubusercontent.com/swaggo/swag/master/assets/swaggo.png">
|
||||
|
||||
[](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)
|
||||
- [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)
|
||||
- [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)
|
||||
- [About the Project](#about-the-project)
|
||||
|
||||
## Getting started
|
||||
|
||||
1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).
|
||||
|
||||
2. Download swag by using:
|
||||
```sh
|
||||
$ go get -u github.com/swaggo/swag/cmd/swag
|
||||
|
||||
# 1.16 or newer
|
||||
$ go install github.com/swaggo/swag/cmd/swag@latest
|
||||
```
|
||||
To build from source you need [Go](https://golang.org/dl/) (1.15 or newer).
|
||||
|
||||
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.
|
||||
```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:
|
||||
--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)
|
||||
--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")
|
||||
--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)
|
||||
- [flamingo](https://github.com/i-love-flamingo/swagger)
|
||||
- [fiber](https://github.com/arsmn/fiber-swagger)
|
||||
- [atreugo](https://github.com/Nerzal/atreugo-swagger)
|
||||
|
||||
## How to use it with Gin
|
||||
|
||||
Find the example source code [here](https://github.com/swaggo/swag/tree/master/example/celler).
|
||||
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
## 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 |
|
||||
| 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 named like endpointname.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]` |
|
||||
| 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)
|
||||
- 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 | // @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 |
|
||||
|
||||
|
||||
| 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 |
|
||||
|
||||
|
||||
## 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 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"`
|
||||
Baz int `minimum:"10" maximum:"20" default:"15"`
|
||||
Qux []string `enums:"foo,bar,baz"`
|
||||
}
|
||||
```
|
||||
|
||||
### Available
|
||||
|
||||
Field Name | Type | Description
|
||||
---|:---:|---
|
||||
<a name="validate"></a>validate | `string` | Determines the validation for the parameter. Possible values are: `required`.
|
||||
<a name="parameterDefault"></a>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.
|
||||
<a name="parameterMaximum"></a>maximum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
|
||||
<a name="parameterMinimum"></a>minimum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
|
||||
<a name="parameterMultipleOf"></a>multipleOf | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
|
||||
<a name="parameterMaxLength"></a>maxLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
|
||||
<a name="parameterMinLength"></a>minLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
|
||||
<a name="parameterEnums"></a>enums | [\*] | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
|
||||
<a name="parameterFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](https://swagger.io/specification/v2/#dataTypeFormat) for further details.
|
||||
<a name="parameterCollectionFormat"></a>collectionFormat | `string` |Determines the format of the array if type array is used. Possible values are: <ul><li>`csv` - comma separated values `foo,bar`. <li>`ssv` - space separated values `foo bar`. <li>`tsv` - tab separated values `foo\tbar`. <li>`pipes` - pipe separated values <code>foo|bar</code>. <li>`multi` - corresponds to multiple parameter instances instead of multiple values for a single instance `foo=bar&foo=baz`. This is valid only for parameters [`in`](#parameterIn) "query" or "formData". </ul> Default value is `csv`.
|
||||
<a name="parameterExtensions"></a>extensions | `string` | Add extension to parameters.
|
||||
|
||||
### Future
|
||||
|
||||
Field Name | Type | Description
|
||||
---|:---:|---
|
||||
<a name="parameterPattern"></a>pattern | `string` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
|
||||
<a name="parameterMaxItems"></a>maxItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
|
||||
<a name="parameterMinItems"></a>minItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
|
||||
<a name="parameterUniqueItems"></a>uniqueItems | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
|
||||
|
||||
## Examples
|
||||
|
||||
### Descriptions over multiple lines
|
||||
|
||||
You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:
|
||||
|
||||
```go
|
||||
// @description This is the first line
|
||||
// @description This is the second line
|
||||
// @description And so forth.
|
||||
```
|
||||
|
||||
### User defined structure with an array type
|
||||
|
||||
```go
|
||||
// @Success 200 {array} model.Account <-- This is a user defined struct.
|
||||
```
|
||||
|
||||
```go
|
||||
package model
|
||||
|
||||
type Account struct {
|
||||
ID int `json:"id" example:"1"`
|
||||
Name string `json:"name" example:"account name"`
|
||||
}
|
||||
```
|
||||
|
||||
### Model composition in response
|
||||
```go
|
||||
// JSONResult's data field will be overridden by the specific type proto.Order
|
||||
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
|
||||
```
|
||||
|
||||
```go
|
||||
type JSONResult struct {
|
||||
Code int `json:"code" `
|
||||
Message string `json:"message"`
|
||||
Data interface{} `json:"data"`
|
||||
}
|
||||
|
||||
type Order struct { //in `proto` package
|
||||
Id uint `json:"id"`
|
||||
Data interface{} `json:"data"`
|
||||
}
|
||||
```
|
||||
|
||||
- also support array of objects and primitive types as nested response
|
||||
```go
|
||||
@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
|
||||
@success 200 {object} jsonresult.JSONResult{data=string} "desc"
|
||||
@success 200 {object} jsonresult.JSONResult{data=[]string} "desc"
|
||||
```
|
||||
|
||||
- overriding multiple fields. field will be added if not exists
|
||||
```go
|
||||
@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
|
||||
```
|
||||
- overriding deep-level fields
|
||||
```go
|
||||
type DeepObject struct { //in `proto` package
|
||||
...
|
||||
}
|
||||
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"
|
||||
```
|
||||
### Add a headers in response
|
||||
|
||||
```go
|
||||
// @Success 200 {string} string "ok"
|
||||
// @failure 400 {string} string "error"
|
||||
// @response default {string} string "other error"
|
||||
// @Header 200 {string} Location "/entity/1"
|
||||
// @Header 200,400,default {string} Token "token"
|
||||
// @Header all {string} Token2 "token2"
|
||||
```
|
||||
|
||||
### Use multiple path params
|
||||
|
||||
```go
|
||||
/// ...
|
||||
// @Param group_id path int true "Group ID"
|
||||
// @Param account_id path int true "Account ID"
|
||||
// ...
|
||||
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]
|
||||
```
|
||||
|
||||
### Add multiple paths
|
||||
|
||||
```go
|
||||
/// ...
|
||||
// @Param group_id path int true "Group ID"
|
||||
// @Param user_id path int true "User ID"
|
||||
// ...
|
||||
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
|
||||
// @Router /examples/user/{user_id}/address [put]
|
||||
```
|
||||
|
||||
### Example value of struct
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID int `json:"id" example:"1"`
|
||||
Name string `json:"name" example:"account name"`
|
||||
PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
|
||||
}
|
||||
```
|
||||
|
||||
### Description of struct
|
||||
|
||||
```go
|
||||
// Account model info
|
||||
// @Description User account information
|
||||
// @Description with user id and username
|
||||
type Account struct {
|
||||
// ID this is userid
|
||||
ID int `json:"id"`
|
||||
Name string `json:"name"` // This is Name
|
||||
}
|
||||
```
|
||||
|
||||
[#708](https://github.com/swaggo/swag/issues/708) The parser handles only struct comments starting with `@Description` attribute.
|
||||
But it writes all struct field comments as is.
|
||||
|
||||
So, generated swagger doc as follows:
|
||||
```json
|
||||
"Account": {
|
||||
"type":"object",
|
||||
"description": "User account information with user id and username"
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer",
|
||||
"description": "ID this is userid"
|
||||
},
|
||||
"name": {
|
||||
"type":"string",
|
||||
"description": "This is Name"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use swaggertype tag to supported custom type
|
||||
[#201](https://github.com/swaggo/swag/issues/201#issuecomment-475479409)
|
||||
|
||||
```go
|
||||
type TimestampTime struct {
|
||||
time.Time
|
||||
}
|
||||
|
||||
///implement encoding.JSON.Marshaler interface
|
||||
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
|
||||
bin := make([]byte, 16)
|
||||
bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
|
||||
return bin, nil
|
||||
}
|
||||
|
||||
func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
|
||||
v, err := strconv.ParseInt(string(bin), 10, 64)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
t.Time = time.Unix(v, 0)
|
||||
return nil
|
||||
}
|
||||
///
|
||||
|
||||
type Account struct {
|
||||
// Override primitive type by simply specifying it via `swaggertype` tag
|
||||
ID sql.NullInt64 `json:"id" swaggertype:"integer"`
|
||||
|
||||
// Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
|
||||
RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
|
||||
|
||||
// Array types can be overridden using "array,<prim_type>" format
|
||||
Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
|
||||
}
|
||||
```
|
||||
|
||||
[#379](https://github.com/swaggo/swag/issues/379)
|
||||
```go
|
||||
type CerticateKeyPair struct {
|
||||
Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
|
||||
Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
|
||||
}
|
||||
```
|
||||
generated swagger doc as follows:
|
||||
```go
|
||||
"api.MyBinding": {
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"crt":{
|
||||
"type":"string",
|
||||
"format":"base64",
|
||||
"example":"U3dhZ2dlciByb2Nrcw=="
|
||||
},
|
||||
"key":{
|
||||
"type":"string",
|
||||
"format":"base64",
|
||||
"example":"U3dhZ2dlciByb2Nrcw=="
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Use global overrides to support a custom type
|
||||
|
||||
If you are using generated files, the [`swaggertype`](#use-swaggertype-tag-to-supported-custom-type) or `swaggerignore` tags may not be possible.
|
||||
|
||||
By passing a mapping to swag with `--overridesFile` you can tell swag to use one type in place of another wherever it appears. By default, if a `.swaggo` file is present in the current directory it will be used.
|
||||
|
||||
Go code:
|
||||
```go
|
||||
type MyStruct struct {
|
||||
ID sql.NullInt64 `json:"id"`
|
||||
Name sql.NullString `json:"name"`
|
||||
}
|
||||
```
|
||||
|
||||
`.swaggo`:
|
||||
```
|
||||
// Replace all NullInt64 with int
|
||||
replace database/sql.NullInt64 int
|
||||
|
||||
// Don't include any fields of type database/sql.NullString in the swagger docs
|
||||
skip database/sql.NullString
|
||||
```
|
||||
|
||||
Possible directives are comments (beginning with `//`), `replace path/to/a.type path/to/b.type`, and `skip path/to/a.type`.
|
||||
|
||||
(Note that the full paths to any named types must be provided to prevent problems when multiple packages define a type with the same name)
|
||||
|
||||
Rendered:
|
||||
```go
|
||||
"types.MyStruct": {
|
||||
"id": "integer"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Use swaggerignore tag to exclude a field
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Ignored int `swaggerignore:"true"`
|
||||
}
|
||||
```
|
||||
|
||||
### Add extension info to struct field
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID string `json:"id" extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
|
||||
}
|
||||
```
|
||||
|
||||
generate swagger doc as follows:
|
||||
|
||||
```go
|
||||
"Account": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"x-nullable": true,
|
||||
"x-abc": "def",
|
||||
"x-omitempty": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
### Rename model to display
|
||||
|
||||
```golang
|
||||
type Resp struct {
|
||||
Code int
|
||||
}//@name Response
|
||||
```
|
||||
|
||||
### How to use security annotations
|
||||
|
||||
General API info.
|
||||
|
||||
```go
|
||||
// @securityDefinitions.basic BasicAuth
|
||||
|
||||
// @securitydefinitions.oauth2.application OAuth2Application
|
||||
// @tokenUrl https://example.com/oauth/token
|
||||
// @scope.write Grants write access
|
||||
// @scope.admin Grants read and write access to administrative information
|
||||
```
|
||||
|
||||
Each API operation.
|
||||
|
||||
```go
|
||||
// @Security ApiKeyAuth
|
||||
```
|
||||
|
||||
Make it AND condition
|
||||
|
||||
```go
|
||||
// @Security ApiKeyAuth
|
||||
// @Security OAuth2Application[write, admin]
|
||||
```
|
||||
|
||||
### Add a description for enum items
|
||||
|
||||
```go
|
||||
type Example struct {
|
||||
// Sort order:
|
||||
// * asc - Ascending, from A to Z.
|
||||
// * desc - Descending, from Z to A.
|
||||
Order string `enums:"asc,desc"`
|
||||
}
|
||||
```
|
||||
|
||||
### Generate only specific docs file types
|
||||
|
||||
By default `swag` command generates Swagger specification in three different files/file types:
|
||||
- docs.go
|
||||
- swagger.json
|
||||
- swagger.yaml
|
||||
|
||||
If you would like to limit a set of file types which should be generated you can use `--outputTypes` (short `-ot`) flag. Default value is `go,json,yaml` - output types separated with comma. To limit output only to `go` and `yaml` files, you would write `go,yaml`. With complete command that would be `swag init --outputTypes go,yaml`.
|
||||
|
||||
## About the Project
|
||||
This project was inspired by [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). It has licenses [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en).
|
||||
## Contributors
|
||||
|
||||
This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
|
||||
<a href="https://github.com/swaggo/swag/graphs/contributors"><img src="https://opencollective.com/swag/contributors.svg?width=890&button=false" /></a>
|
||||
|
||||
|
||||
## Backers
|
||||
|
||||
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]
|
||||
|
||||
<a href="https://opencollective.com/swag#backers" target="_blank"><img src="https://opencollective.com/swag/backers.svg?width=890"></a>
|
||||
|
||||
|
||||
## 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)]
|
||||
|
||||
<a href="https://opencollective.com/swag/sponsor/0/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/0/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/1/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/1/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/2/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/2/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/3/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/3/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/4/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/4/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/5/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/5/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/6/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/6/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/7/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/7/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/8/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/8/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/9/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/9/avatar.svg"></a>
|
||||
|
||||
|
||||
|
||||
|
||||
## License
|
||||
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)
|
||||
760
vendor/github.com/swaggo/swag/README_zh-CN.md
generated
vendored
Normal file
760
vendor/github.com/swaggo/swag/README_zh-CN.md
generated
vendored
Normal file
@@ -0,0 +1,760 @@
|
||||
# swag
|
||||
|
||||
🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md)*
|
||||
|
||||
<img align="right" width="180px" src="https://raw.githubusercontent.com/swaggo/swag/master/assets/swaggo.png">
|
||||
|
||||
[](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 get -u github.com/swaggo/swag/cmd/swag
|
||||
|
||||
# 1.16 及以上版本
|
||||
$ go install github.com/swaggo/swag/cmd/swag@latest
|
||||
```
|
||||
|
||||
从源码开始构建的话，需要有Go环境（1.15及以上版本）。
|
||||
|
||||
或者从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)
|
||||
|
||||
## 如何与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
|
||||
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-types)”中所述。 | // @accept json |
|
||||
| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime-types)”中所述。 | // @produce json |
|
||||
| query.collection.format | 请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。 | // @query.collection.format multi |
|
||||
| schemes | 用空格分隔的请求的传输协议。 | // @schemes http https |
|
||||
| x-name | 扩展的键必须以x-开头，并且只能使用json值 | // @x-example-key {"key": "value"} |
|
||||
|
||||
### 使用Markdown描述
|
||||
|
||||
如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。
|
||||
|
||||
| 注释 | 说明 | 示例 |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
|
||||
| title | **必填** 应用程序的名称。 | // @title Swagger Example API |
|
||||
| version | **必填** 提供应用程序API的版本。 | // @version 1.0 |
|
||||
| description.markdown | 应用程序的简短描述。 从`api.md`文件中解析。 这是`@description`的替代用法。 | // @description.markdown No value needed, this parses the description from api.md |
|
||||
| tag.name | 标签的名称。 | // @tag.name This is the name of the tag |
|
||||
| tag.description.markdown | 标签说明，这是`tag.description`的替代用法。 该描述将从名为`tagname.md的`文件中读取。 | // @tag.description.markdown |
|
||||
|
||||
## API操作
|
||||
|
||||
Example [celler/controller](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-types)”中所述。 |
|
||||
| produce | API可以生成的MIME类型的列表。值必须如“[Mime类型](#mime-types)”中所述。 |
|
||||
| param | 用空格分隔的参数。`param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
|
||||
| security | 每个API操作的[安全性](#安全性)。 |
|
||||
| success | 以空格分隔的成功响应。`return code`,`{param type}`,`data type`,`comment` |
|
||||
| failure | 以空格分隔的故障响应。`return code`,`{param type}`,`data type`,`comment` |
|
||||
| response | 与success、failure作用相同 |
|
||||
| header | 以空格分隔的头字段。 `return code`,`{param type}`,`data type`,`comment` |
|
||||
| router | 以空格分隔的路径定义。 `path`,`[httpMethod]` |
|
||||
| x-name | 扩展字段必须以`x-`开头，并且只能使用json值。 |
|
||||
|
||||
## Mime类型
|
||||
|
||||
`swag` 接受所有格式正确的MIME类型, 即使匹配 `*/*`。除此之外，`swag`还接受某些MIME类型的别名，如下所示：
|
||||
|
||||
| Alias | MIME Type |
|
||||
| --------------------- | --------------------------------- |
|
||||
| json | application/json |
|
||||
| xml | text/xml |
|
||||
| plain | text/plain |
|
||||
| html | text/html |
|
||||
| mpfd | multipart/form-data |
|
||||
| x-www-form-urlencoded | application/x-www-form-urlencoded |
|
||||
| json-api | application/vnd.api+json |
|
||||
| json-stream | application/x-json-stream |
|
||||
| octet-stream | application/octet-stream |
|
||||
| png | image/png |
|
||||
| jpeg | image/jpeg |
|
||||
| gif | image/gif |
|
||||
|
||||
## 参数类型
|
||||
|
||||
- query
|
||||
- path
|
||||
- header
|
||||
- body
|
||||
- formData
|
||||
|
||||
## 数据类型
|
||||
|
||||
- string (string)
|
||||
- integer (int, uint, uint32, uint64)
|
||||
- number (float32)
|
||||
- boolean (bool)
|
||||
- user defined struct
|
||||
|
||||
## 安全性
|
||||
|
||||
| 注释 | 描述 | 参数 | 示例 |
|
||||
| -------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------ |
|
||||
| securitydefinitions.basic | [Basic](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数组参数的格式。 可能的值为： <ul><li>`csv` - 逗号分隔值 `foo,bar`. <li>`ssv` - 空格分隔值 `foo bar`. <li>`tsv` - 制表符分隔值 `foo\tbar`. <li>`pipes` - 管道符分隔值 <code>foo|bar</code>. <li>`multi` - 对应于多个参数实例，而不是单个实例 `foo=bar＆foo=baz` 的多个值。这仅对“`query`”或“`formData`”中的参数有效。 </ul> 默认值是 `csv`。 |
|
||||
|
||||
### 进一步的
|
||||
|
||||
| 字段名 | 类型 | 描述 |
|
||||
| ----------- | :-------: | ---------------------------------------------------------------------------------- |
|
||||
| multipleOf | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
|
||||
| pattern | `string` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
|
||||
| maxItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
|
||||
| minItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
|
||||
| uniqueItems | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
|
||||
|
||||
## 样例
|
||||
|
||||
### 多行的描述
|
||||
|
||||
可以在常规api描述或路由定义中添加跨越多行的描述，如下所示：
|
||||
|
||||
```go
|
||||
// @description This is the first line
|
||||
// @description This is the second line
|
||||
// @description And so forth.
|
||||
```
|
||||
|
||||
### 用户自定义的具有数组类型的结构
|
||||
|
||||
```go
|
||||
// @Success 200 {array} model.Account <-- This is a user defined struct.
|
||||
```
|
||||
|
||||
```go
|
||||
package model
|
||||
|
||||
type Account struct {
|
||||
ID int `json:"id" example:"1"`
|
||||
Name string `json:"name" example:"account name"`
|
||||
}
|
||||
```
|
||||
|
||||
### 响应对象中的模型组合
|
||||
|
||||
```go
|
||||
// JSONResult的data字段类型将被proto.Order类型替换
|
||||
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
|
||||
```
|
||||
|
||||
```go
|
||||
type JSONResult struct {
|
||||
Code int `json:"code" `
|
||||
Message string `json:"message"`
|
||||
Data interface{} `json:"data"`
|
||||
}
|
||||
|
||||
type Order struct { //in `proto` package
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- 还支持对象数组和原始类型作为嵌套响应
|
||||
|
||||
```go
|
||||
@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
|
||||
@success 200 {object} jsonresult.JSONResult{data=string} "desc"
|
||||
@success 200 {object} jsonresult.JSONResult{data=[]string} "desc"
|
||||
```
|
||||
|
||||
- 替换多个字段的类型。如果某字段不存在，将添加该字段。
|
||||
|
||||
```go
|
||||
@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
|
||||
```
|
||||
|
||||
### 在响应中增加头字段
|
||||
|
||||
```go
|
||||
// @Success 200 {string} string "ok"
|
||||
// @failure 400 {string} string "error"
|
||||
// @response default {string} string "other error"
|
||||
// @Header 200 {string} Location "/entity/1"
|
||||
// @Header 200,400,default {string} Token "token"
|
||||
// @Header all {string} Token2 "token2"
|
||||
```
|
||||
|
||||
### 使用多路径参数
|
||||
|
||||
```go
|
||||
/// ...
|
||||
// @Param group_id path int true "Group ID"
|
||||
// @Param account_id path int true "Account ID"
|
||||
// ...
|
||||
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]
|
||||
```
|
||||
|
||||
### 结构体的示例值
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID int `json:"id" example:"1"`
|
||||
Name string `json:"name" example:"account name"`
|
||||
PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
|
||||
}
|
||||
```
|
||||
|
||||
### 结构体描述
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
// ID this is userid
|
||||
ID int `json:"id"`
|
||||
Name string `json:"name"` // This is Name
|
||||
}
|
||||
```
|
||||
|
||||
### 使用`swaggertype`标签更改字段类型
|
||||
|
||||
[#201](https://github.com/swaggo/swag/issues/201#issuecomment-475479409)
|
||||
|
||||
```go
|
||||
type TimestampTime struct {
|
||||
time.Time
|
||||
}
|
||||
|
||||
///实现encoding.JSON.Marshaler接口
|
||||
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
|
||||
bin := make([]byte, 16)
|
||||
bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
|
||||
return bin, nil
|
||||
}
|
||||
|
||||
///实现encoding.JSON.Unmarshaler接口
|
||||
func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
|
||||
v, err := strconv.ParseInt(string(bin), 10, 64)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
t.Time = time.Unix(v, 0)
|
||||
return nil
|
||||
}
|
||||
///
|
||||
|
||||
type Account struct {
|
||||
// 使用`swaggertype`标签将别名类型更改为内置类型integer
|
||||
ID sql.NullInt64 `json:"id" swaggertype:"integer"`
|
||||
|
||||
// 使用`swaggertype`标签更改struct类型为内置类型integer
|
||||
RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
|
||||
|
||||
// Array types can be overridden using "array,<prim_type>" format
|
||||
Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
|
||||
}
|
||||
```
|
||||
|
||||
[#379](https://github.com/swaggo/swag/issues/379)
|
||||
|
||||
```go
|
||||
type CerticateKeyPair struct {
|
||||
Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
|
||||
Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
|
||||
}
|
||||
```
|
||||
|
||||
生成的swagger文档如下：
|
||||
|
||||
```go
|
||||
"api.MyBinding": {
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"crt":{
|
||||
"type":"string",
|
||||
"format":"base64",
|
||||
"example":"U3dhZ2dlciByb2Nrcw=="
|
||||
},
|
||||
"key":{
|
||||
"type":"string",
|
||||
"format":"base64",
|
||||
"example":"U3dhZ2dlciByb2Nrcw=="
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 使用`swaggerignore`标签排除字段
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Ignored int `swaggerignore:"true"`
|
||||
}
|
||||
```
|
||||
|
||||
### 将扩展信息添加到结构字段
|
||||
|
||||
```go
|
||||
type Account struct {
|
||||
ID string `json:"id" extensions:"x-nullable,x-abc=def,!x-omitempty"` // 扩展字段必须以"x-"开头
|
||||
}
|
||||
```
|
||||
|
||||
生成swagger文档，如下所示：
|
||||
|
||||
```go
|
||||
"Account": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"x-nullable": true,
|
||||
"x-abc": "def",
|
||||
"x-omitempty": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 对展示的模型重命名
|
||||
|
||||
```go
|
||||
type Resp struct {
|
||||
Code int
|
||||
}//@name Response
|
||||
```
|
||||
|
||||
### 如何使用安全性注释
|
||||
|
||||
通用API信息。
|
||||
|
||||
```go
|
||||
// @securityDefinitions.basic BasicAuth
|
||||
|
||||
// @securitydefinitions.oauth2.application OAuth2Application
|
||||
// @tokenUrl https://example.com/oauth/token
|
||||
// @scope.write Grants write access
|
||||
// @scope.admin Grants read and write access to administrative information
|
||||
```
|
||||
|
||||
每个API操作。
|
||||
|
||||
```go
|
||||
// @Security ApiKeyAuth
|
||||
```
|
||||
|
||||
使用AND条件。
|
||||
|
||||
```go
|
||||
// @Security ApiKeyAuth
|
||||
// @Security OAuth2Application[write, admin]
|
||||
```
|
||||
|
||||
## 项目相关
|
||||
|
||||
This project was inspired by [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). It has licenses [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en).
|
||||
|
||||
## 贡献者
|
||||
|
||||
This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
|
||||
<a href="https://github.com/swaggo/swag/graphs/contributors"><img src="https://opencollective.com/swag/contributors.svg?width=890&button=false" /></a>
|
||||
|
||||
## 支持者
|
||||
|
||||
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]
|
||||
|
||||
<a href="https://opencollective.com/swag#backers" target="_blank"><img src="https://opencollective.com/swag/backers.svg?width=890"></a>
|
||||
|
||||
## 赞助商
|
||||
|
||||
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)]
|
||||
|
||||
<a href="https://opencollective.com/swag/sponsor/0/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/0/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/1/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/1/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/2/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/2/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/3/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/3/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/4/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/4/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/5/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/5/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/6/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/6/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/7/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/7/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/8/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/8/avatar.svg"></a>
|
||||
<a href="https://opencollective.com/swag/sponsor/9/website" target="_blank"><img src="https://opencollective.com/swag/sponsor/9/avatar.svg"></a>
|
||||
|
||||
## License
|
||||
|
||||
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)
|
||||
5
vendor/github.com/swaggo/swag/doc.go
generated
vendored
Normal file
5
vendor/github.com/swaggo/swag/doc.go
generated
vendored
Normal file
@@ -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"
|
||||
582
vendor/github.com/swaggo/swag/field_parser.go
generated
vendored
Normal file
582
vendor/github.com/swaggo/swag/field_parser.go
generated
vendored
Normal file
@@ -0,0 +1,582 @@
|
||||
package swag
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"reflect"
|
||||
"regexp"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
"unicode"
|
||||
|
||||
"github.com/go-openapi/spec"
|
||||
)
|
||||
|
||||
var _ FieldParser = &tagBaseFieldParser{}
|
||||
|
||||
type tagBaseFieldParser struct {
|
||||
p *Parser
|
||||
field *ast.Field
|
||||
tag reflect.StructTag
|
||||
}
|
||||
|
||||
func newTagBaseFieldParser(p *Parser, field *ast.Field) FieldParser {
|
||||
ps := &tagBaseFieldParser{
|
||||
p: p,
|
||||
field: field,
|
||||
}
|
||||
if ps.field.Tag != nil {
|
||||
ps.tag = reflect.StructTag(strings.Replace(field.Tag.Value, "`", "", -1))
|
||||
}
|
||||
|
||||
return ps
|
||||
}
|
||||
|
||||
func (ps *tagBaseFieldParser) ShouldSkip() (bool, error) {
|
||||
// Skip non-exported fields.
|
||||
if !ast.IsExported(ps.field.Names[0].Name) {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
if ps.field.Tag == nil {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
ignoreTag := ps.tag.Get("swaggerignore")
|
||||
if strings.EqualFold(ignoreTag, "true") {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
// json:"tag,hoge"
|
||||
name := strings.TrimSpace(strings.Split(ps.tag.Get("json"), ",")[0])
|
||||
if name == "-" {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
return false, nil
|
||||
}
|
||||
|
||||
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("json"), ",")[0])
|
||||
|
||||
if name != "" {
|
||||
return name, 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 toSnakeCase(in string) string {
|
||||
runes := []rune(in)
|
||||
length := len(runes)
|
||||
|
||||
var out []rune
|
||||
for i := 0; i < length; i++ {
|
||||
if i > 0 && unicode.IsUpper(runes[i]) &&
|
||||
((i+1 < length && unicode.IsLower(runes[i+1])) || unicode.IsLower(runes[i-1])) {
|
||||
out = append(out, '_')
|
||||
}
|
||||
out = append(out, unicode.ToLower(runes[i]))
|
||||
}
|
||||
|
||||
return string(out)
|
||||
}
|
||||
|
||||
func toLowerCamelCase(in string) string {
|
||||
runes := []rune(in)
|
||||
|
||||
var out []rune
|
||||
flag := false
|
||||
for i, curr := range runes {
|
||||
if (i == 0 && unicode.IsUpper(curr)) || (flag && unicode.IsUpper(curr)) {
|
||||
out = append(out, unicode.ToLower(curr))
|
||||
flag = true
|
||||
} else {
|
||||
out = append(out, 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("swaggertype")
|
||||
if typeTag != "" {
|
||||
return BuildCustomSchema(strings.Split(typeTag, ","))
|
||||
}
|
||||
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
type structField struct {
|
||||
desc string
|
||||
schemaType string
|
||||
arrayType string
|
||||
formatType string
|
||||
maximum *float64
|
||||
minimum *float64
|
||||
multipleOf *float64
|
||||
maxLength *int64
|
||||
minLength *int64
|
||||
maxItems *int64
|
||||
minItems *int64
|
||||
exampleValue interface{}
|
||||
defaultValue interface{}
|
||||
extensions map[string]interface{}
|
||||
enums []interface{}
|
||||
enumVarNames []interface{}
|
||||
readOnly bool
|
||||
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{
|
||||
'(': ')',
|
||||
'[': ']',
|
||||
'{': '}',
|
||||
}
|
||||
|
||||
result := make([]string, 0)
|
||||
current := ""
|
||||
var openCount = 0
|
||||
var openChar rune
|
||||
for _, char := range s {
|
||||
if openChar == 0 && openCloseMap[char] != 0 {
|
||||
openChar = char
|
||||
openCount++
|
||||
current += string(char)
|
||||
} else if char == openChar {
|
||||
openCount++
|
||||
current = current + string(char)
|
||||
} else if openCount > 0 && char == openCloseMap[openChar] {
|
||||
openCount--
|
||||
current += string(char)
|
||||
} else if openCount == 0 && char == sep {
|
||||
result = append(result, current)
|
||||
openChar = 0
|
||||
current = ""
|
||||
} else {
|
||||
current += string(char)
|
||||
}
|
||||
}
|
||||
|
||||
if current != "" {
|
||||
result = append(result, current)
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
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 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
|
||||
}
|
||||
|
||||
structField := &structField{
|
||||
schemaType: types[0],
|
||||
formatType: ps.tag.Get(formatTag),
|
||||
readOnly: ps.tag.Get(readOnlyTag) == "true",
|
||||
}
|
||||
|
||||
if len(types) > 1 && (types[0] == ARRAY || types[0] == OBJECT) {
|
||||
structField.arrayType = types[1]
|
||||
}
|
||||
|
||||
if ps.field.Doc != nil {
|
||||
structField.desc = strings.TrimSpace(ps.field.Doc.Text())
|
||||
}
|
||||
if structField.desc == "" && ps.field.Comment != nil {
|
||||
structField.desc = strings.TrimSpace(ps.field.Comment.Text())
|
||||
}
|
||||
|
||||
jsonTag := ps.tag.Get(jsonTag)
|
||||
// json:"name,string" or json:",string"
|
||||
|
||||
exampleTag, ok := ps.tag.Lookup(exampleTag)
|
||||
if ok {
|
||||
structField.exampleValue = exampleTag
|
||||
if !strings.Contains(jsonTag, ",string") {
|
||||
example, err := defineTypeOfExample(structField.schemaType, structField.arrayType, exampleTag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
structField.exampleValue = example
|
||||
}
|
||||
}
|
||||
|
||||
bindingTag := ps.tag.Get(bindingTag)
|
||||
if bindingTag != "" {
|
||||
ps.parseValidTags(bindingTag, structField)
|
||||
}
|
||||
|
||||
validateTag := ps.tag.Get(validateTag)
|
||||
if validateTag != "" {
|
||||
ps.parseValidTags(validateTag, structField)
|
||||
}
|
||||
|
||||
extensionsTag := ps.tag.Get(extensionsTag)
|
||||
if extensionsTag != "" {
|
||||
structField.extensions = map[string]interface{}{}
|
||||
for _, val := range splitNotWrapped(extensionsTag, ',') {
|
||||
parts := strings.SplitN(val, "=", 2)
|
||||
if len(parts) == 2 {
|
||||
structField.extensions[parts[0]] = parts[1]
|
||||
} else {
|
||||
if len(parts[0]) > 0 && string(parts[0][0]) == "!" {
|
||||
structField.extensions[parts[0][1:]] = false
|
||||
} else {
|
||||
structField.extensions[parts[0]] = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
enumsTag := ps.tag.Get(enumsTag)
|
||||
if enumsTag != "" {
|
||||
enumType := structField.schemaType
|
||||
if structField.schemaType == ARRAY {
|
||||
enumType = structField.arrayType
|
||||
}
|
||||
|
||||
structField.enums = nil
|
||||
for _, e := range strings.Split(enumsTag, ",") {
|
||||
value, err := defineType(enumType, e)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
structField.enums = append(structField.enums, value)
|
||||
}
|
||||
}
|
||||
varnamesTag := ps.tag.Get("x-enum-varnames")
|
||||
if varnamesTag != "" {
|
||||
if structField.extensions == nil {
|
||||
structField.extensions = map[string]interface{}{}
|
||||
}
|
||||
varNames := strings.Split(varnamesTag, ",")
|
||||
if len(varNames) != len(structField.enums) {
|
||||
return fmt.Errorf("invalid count of x-enum-varnames. expected %d, got %d", len(structField.enums), len(varNames))
|
||||
}
|
||||
structField.enumVarNames = nil
|
||||
for _, v := range varNames {
|
||||
structField.enumVarNames = append(structField.enumVarNames, v)
|
||||
}
|
||||
structField.extensions["x-enum-varnames"] = structField.enumVarNames
|
||||
}
|
||||
defaultTag := ps.tag.Get(defaultTag)
|
||||
if defaultTag != "" {
|
||||
value, err := defineType(structField.schemaType, defaultTag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
structField.defaultValue = value
|
||||
}
|
||||
|
||||
if IsNumericType(structField.schemaType) || IsNumericType(structField.arrayType) {
|
||||
maximum, err := getFloatTag(ps.tag, maximumTag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if maximum != nil {
|
||||
structField.maximum = maximum
|
||||
}
|
||||
|
||||
minimum, err := getFloatTag(ps.tag, minimumTag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if minimum != nil {
|
||||
structField.minimum = minimum
|
||||
}
|
||||
|
||||
multipleOf, err := getFloatTag(ps.tag, multipleOfTag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if multipleOf != nil {
|
||||
structField.multipleOf = multipleOf
|
||||
}
|
||||
}
|
||||
|
||||
if structField.schemaType == STRING || structField.arrayType == STRING {
|
||||
maxLength, err := getIntTag(ps.tag, "maxLength")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if maxLength != nil {
|
||||
structField.maxLength = maxLength
|
||||
}
|
||||
|
||||
minLength, err := getIntTag(ps.tag, "minLength")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if minLength != nil {
|
||||
structField.minLength = minLength
|
||||
}
|
||||
}
|
||||
|
||||
// perform this after setting everything else (min, max, etc...)
|
||||
if strings.Contains(jsonTag, ",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[structField.schemaType]
|
||||
if ok {
|
||||
structField.schemaType = STRING
|
||||
|
||||
if structField.exampleValue == nil {
|
||||
// if exampleValue is not defined by the user,
|
||||
// we will force an example with a correct value
|
||||
// (eg: int->"0", bool:"false")
|
||||
structField.exampleValue = defaultValue
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if structField.schemaType == STRING && types[0] != STRING {
|
||||
*schema = *PrimitiveSchema(structField.schemaType)
|
||||
}
|
||||
|
||||
schema.Description = structField.desc
|
||||
schema.ReadOnly = structField.readOnly
|
||||
if !reflect.ValueOf(schema.Ref).IsZero() && schema.ReadOnly {
|
||||
schema.AllOf = []spec.Schema{*spec.RefSchema(schema.Ref.String())}
|
||||
schema.Ref = spec.Ref{} // clear out existing ref
|
||||
}
|
||||
schema.Default = structField.defaultValue
|
||||
schema.Example = structField.exampleValue
|
||||
if structField.schemaType != ARRAY {
|
||||
schema.Format = structField.formatType
|
||||
}
|
||||
schema.Extensions = structField.extensions
|
||||
eleSchema := schema
|
||||
if structField.schemaType == ARRAY {
|
||||
// For Array only
|
||||
schema.MaxItems = structField.maxItems
|
||||
schema.MinItems = structField.minItems
|
||||
schema.UniqueItems = structField.unique
|
||||
|
||||
eleSchema = schema.Items.Schema
|
||||
eleSchema.Format = structField.formatType
|
||||
}
|
||||
eleSchema.Maximum = structField.maximum
|
||||
eleSchema.Minimum = structField.minimum
|
||||
eleSchema.MultipleOf = structField.multipleOf
|
||||
eleSchema.MaxLength = structField.maxLength
|
||||
eleSchema.MinLength = structField.minLength
|
||||
eleSchema.Enum = structField.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, ",") {
|
||||
if val == "required" {
|
||||
return true, nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
validateTag := ps.tag.Get(validateTag)
|
||||
if validateTag != "" {
|
||||
for _, val := range strings.Split(validateTag, ",") {
|
||||
if val == "required" {
|
||||
return true, nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false, nil
|
||||
}
|
||||
|
||||
func (ps *tagBaseFieldParser) parseValidTags(validTag string, sf *structField) {
|
||||
// `validate:"required,max=10,min=1"`
|
||||
// ps. required checked by IsRequired().
|
||||
for _, val := range strings.Split(validTag, ",") {
|
||||
var (
|
||||
valKey string
|
||||
valValue string
|
||||
)
|
||||
kv := strings.Split(val, "=")
|
||||
switch len(kv) {
|
||||
case 1:
|
||||
valKey = kv[0]
|
||||
case 2:
|
||||
valKey = kv[0]
|
||||
valValue = kv[1]
|
||||
default:
|
||||
continue
|
||||
}
|
||||
valValue = strings.Replace(strings.Replace(valValue, utf8HexComma, ",", -1), utf8Pipe, "|", -1)
|
||||
|
||||
switch valKey {
|
||||
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 (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(s string) []string {
|
||||
oneofValsCacheRWLock.RLock()
|
||||
values, ok := oneofValsCache[s]
|
||||
oneofValsCacheRWLock.RUnlock()
|
||||
if !ok {
|
||||
oneofValsCacheRWLock.Lock()
|
||||
values = splitParamsRegex.FindAllString(s, -1)
|
||||
for i := 0; i < len(values); i++ {
|
||||
values[i] = strings.Replace(values[i], "'", "", -1)
|
||||
}
|
||||
oneofValsCache[s] = values
|
||||
oneofValsCacheRWLock.Unlock()
|
||||
}
|
||||
return values
|
||||
}
|
||||
|
||||
// ---
|
||||
326
vendor/github.com/swaggo/swag/formater.go
generated
vendored
Normal file
326
vendor/github.com/swaggo/swag/formater.go
generated
vendored
Normal file
@@ -0,0 +1,326 @@
|
||||
package swag
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"crypto/md5"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
goparser "go/parser"
|
||||
"go/token"
|
||||
"io"
|
||||
"io/ioutil"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"runtime"
|
||||
"strings"
|
||||
"text/tabwriter"
|
||||
)
|
||||
|
||||
const splitTag = "&*"
|
||||
|
||||
// Formater implements a formater for Go source files.
|
||||
type Formater struct {
|
||||
// debugging output goes here
|
||||
debug Debugger
|
||||
|
||||
// excludes excludes dirs and files in SearchDir
|
||||
excludes map[string]struct{}
|
||||
|
||||
mainFile string
|
||||
}
|
||||
|
||||
// NewFormater create a new formater instance.
|
||||
func NewFormater() *Formater {
|
||||
formater := &Formater{
|
||||
debug: log.New(os.Stdout, "", log.LstdFlags),
|
||||
excludes: make(map[string]struct{}),
|
||||
}
|
||||
return formater
|
||||
}
|
||||
|
||||
// FormatAPI format the swag comment.
|
||||
func (f *Formater) FormatAPI(searchDir, excludeDir, mainFile string) error {
|
||||
searchDirs := strings.Split(searchDir, ",")
|
||||
for _, searchDir := range searchDirs {
|
||||
if _, err := os.Stat(searchDir); os.IsNotExist(err) {
|
||||
return fmt.Errorf("dir: %s does not exist", searchDir)
|
||||
}
|
||||
}
|
||||
for _, fi := range strings.Split(excludeDir, ",") {
|
||||
fi = strings.TrimSpace(fi)
|
||||
if fi != "" {
|
||||
fi = filepath.Clean(fi)
|
||||
f.excludes[fi] = struct{}{}
|
||||
}
|
||||
}
|
||||
|
||||
// parse main.go
|
||||
absMainAPIFilePath, err := filepath.Abs(filepath.Join(searchDirs[0], mainFile))
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
err = f.FormatMain(absMainAPIFilePath)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
f.mainFile = mainFile
|
||||
|
||||
err = f.formatMultiSearchDir(searchDirs)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *Formater) formatMultiSearchDir(searchDirs []string) error {
|
||||
for _, searchDir := range searchDirs {
|
||||
f.debug.Printf("Format API Info, search dir:%s", searchDir)
|
||||
|
||||
err := filepath.Walk(searchDir, f.visit)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *Formater) visit(path string, fileInfo os.FileInfo, err error) error {
|
||||
if err := walkWith(f.excludes, false)(path, fileInfo); err != nil {
|
||||
return err
|
||||
} else if fileInfo.IsDir() {
|
||||
// skip if file is folder
|
||||
return nil
|
||||
}
|
||||
|
||||
if strings.HasSuffix(strings.ToLower(path), "_test.go") || filepath.Ext(path) != ".go" {
|
||||
// skip if file not has suffix "*.go"
|
||||
return nil
|
||||
}
|
||||
if strings.HasSuffix(strings.ToLower(path), f.mainFile) {
|
||||
// skip main file
|
||||
return nil
|
||||
}
|
||||
|
||||
err = f.FormatFile(path)
|
||||
if err != nil {
|
||||
return fmt.Errorf("ParseFile error:%+v", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// FormatMain format the main.go comment.
|
||||
func (f *Formater) FormatMain(mainFilepath string) error {
|
||||
fileSet := token.NewFileSet()
|
||||
astFile, err := goparser.ParseFile(fileSet, mainFilepath, nil, goparser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("cannot format file, err: %w path : %s ", err, mainFilepath)
|
||||
}
|
||||
var (
|
||||
formatedComments = bytes.Buffer{}
|
||||
// CommentCache
|
||||
oldCommentsMap = make(map[string]string)
|
||||
)
|
||||
|
||||
if astFile.Comments != nil {
|
||||
for _, comment := range astFile.Comments {
|
||||
formatFuncDoc(comment.List, &formatedComments, oldCommentsMap)
|
||||
}
|
||||
}
|
||||
|
||||
return writeFormatedComments(mainFilepath, formatedComments, oldCommentsMap)
|
||||
}
|
||||
|
||||
// FormatFile format the swag comment in go function.
|
||||
func (f *Formater) FormatFile(filepath string) error {
|
||||
fileSet := token.NewFileSet()
|
||||
astFile, err := goparser.ParseFile(fileSet, filepath, nil, goparser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("cannot format file, err: %w path : %s ", err, filepath)
|
||||
}
|
||||
|
||||
var (
|
||||
formatedComments = bytes.Buffer{}
|
||||
// CommentCache
|
||||
oldCommentsMap = make(map[string]string)
|
||||
)
|
||||
|
||||
for _, astDescription := range astFile.Decls {
|
||||
astDeclaration, ok := astDescription.(*ast.FuncDecl)
|
||||
if ok && astDeclaration.Doc != nil && astDeclaration.Doc.List != nil {
|
||||
formatFuncDoc(astDeclaration.Doc.List, &formatedComments, oldCommentsMap)
|
||||
}
|
||||
}
|
||||
|
||||
return writeFormatedComments(filepath, formatedComments, oldCommentsMap)
|
||||
}
|
||||
|
||||
func writeFormatedComments(filepath string, formatedComments bytes.Buffer, oldCommentsMap map[string]string) error {
|
||||
// Replace the file
|
||||
// Read the file
|
||||
srcBytes, err := ioutil.ReadFile(filepath)
|
||||
if err != nil {
|
||||
return fmt.Errorf("cannot open file, err: %w path : %s ", err, filepath)
|
||||
}
|
||||
replaceSrc := string(srcBytes)
|
||||
newComments := strings.Split(formatedComments.String(), "\n")
|
||||
for _, e := range newComments {
|
||||
commentSplit := strings.Split(e, splitTag)
|
||||
if len(commentSplit) == 2 {
|
||||
commentHash, commentContent := commentSplit[0], commentSplit[1]
|
||||
|
||||
if !isBlankComment(commentContent) {
|
||||
replaceSrc = strings.Replace(replaceSrc, oldCommentsMap[commentHash], commentContent, 1)
|
||||
}
|
||||
}
|
||||
}
|
||||
return writeBack(filepath, []byte(replaceSrc), srcBytes)
|
||||
}
|
||||
|
||||
func formatFuncDoc(commentList []*ast.Comment, formatedComments io.Writer, oldCommentsMap map[string]string) {
|
||||
tabw := tabwriter.NewWriter(formatedComments, 0, 0, 2, ' ', 0)
|
||||
|
||||
for _, comment := range commentList {
|
||||
commentLine := comment.Text
|
||||
if isSwagComment(commentLine) || isBlankComment(commentLine) {
|
||||
cmd5 := fmt.Sprintf("%x", md5.Sum([]byte(commentLine)))
|
||||
|
||||
// Find the separator and replace to \t
|
||||
c := separatorFinder(commentLine, '\t')
|
||||
oldCommentsMap[cmd5] = commentLine
|
||||
|
||||
// md5 + splitTag + srcCommentLine
|
||||
// eg. xxx&*@Description get struct array
|
||||
_, _ = fmt.Fprintln(tabw, cmd5+splitTag+c)
|
||||
}
|
||||
}
|
||||
// format by tabwriter
|
||||
_ = tabw.Flush()
|
||||
}
|
||||
|
||||
// Check of @Param @Success @Failure @Response @Header
|
||||
var specialTagForSplit = map[string]byte{
|
||||
paramAttr: 1,
|
||||
successAttr: 1,
|
||||
failureAttr: 1,
|
||||
responseAttr: 1,
|
||||
headerAttr: 1,
|
||||
}
|
||||
|
||||
var skipChar = map[byte]byte{
|
||||
'"': 1,
|
||||
'(': 1,
|
||||
'{': 1,
|
||||
'[': 1,
|
||||
}
|
||||
|
||||
var skipCharEnd = map[byte]byte{
|
||||
'"': 1,
|
||||
')': 1,
|
||||
'}': 1,
|
||||
']': 1,
|
||||
}
|
||||
|
||||
func separatorFinder(comment string, rp byte) string {
|
||||
commentBytes := []byte(comment)
|
||||
commentLine := strings.TrimSpace(strings.TrimLeft(comment, "/"))
|
||||
if len(commentLine) == 0 {
|
||||
return ""
|
||||
}
|
||||
attribute := strings.Fields(commentLine)[0]
|
||||
attrLen := strings.Index(comment, attribute) + len(attribute)
|
||||
attribute = strings.ToLower(attribute)
|
||||
var i = attrLen
|
||||
|
||||
if _, ok := specialTagForSplit[attribute]; ok {
|
||||
var skipFlag bool
|
||||
for ; i < len(commentBytes); i++ {
|
||||
if !skipFlag && commentBytes[i] == ' ' {
|
||||
j := i
|
||||
for j < len(commentBytes) && commentBytes[j] == ' ' {
|
||||
j++
|
||||
}
|
||||
commentBytes = replaceRange(commentBytes, i, j, rp)
|
||||
}
|
||||
if _, ok := skipChar[commentBytes[i]]; ok && !skipFlag {
|
||||
skipFlag = true
|
||||
} else if _, ok := skipCharEnd[commentBytes[i]]; ok && skipFlag {
|
||||
skipFlag = false
|
||||
}
|
||||
}
|
||||
} else {
|
||||
for i < len(commentBytes) && commentBytes[i] == ' ' {
|
||||
i++
|
||||
}
|
||||
if i >= len(commentBytes) {
|
||||
return comment
|
||||
}
|
||||
commentBytes = replaceRange(commentBytes, attrLen, i, rp)
|
||||
}
|
||||
return string(commentBytes)
|
||||
}
|
||||
|
||||
func replaceRange(s []byte, start, end int, new byte) []byte {
|
||||
if start > end || end < 1 {
|
||||
return s
|
||||
}
|
||||
if end > len(s) {
|
||||
end = len(s)
|
||||
}
|
||||
s = append(s[:start], s[end-1:]...)
|
||||
s[start] = new
|
||||
return s
|
||||
}
|
||||
|
||||
var swagCommentExpression = regexp.MustCompile("@[A-z]+")
|
||||
|
||||
func isSwagComment(comment string) bool {
|
||||
return swagCommentExpression.MatchString(strings.ToLower(comment))
|
||||
}
|
||||
|
||||
func isBlankComment(comment string) bool {
|
||||
lc := strings.TrimSpace(comment)
|
||||
return len(lc) == 0
|
||||
}
|
||||
|
||||
// writeBack write to file
|
||||
func writeBack(filepath string, src, old []byte) error {
|
||||
// make a temporary backup before overwriting original
|
||||
bakname, err := backupFile(filepath+".", old, 0644)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
err = ioutil.WriteFile(filepath, src, 0644)
|
||||
if err != nil {
|
||||
_ = os.Rename(bakname, filepath)
|
||||
return err
|
||||
}
|
||||
_ = os.Remove(bakname)
|
||||
return nil
|
||||
}
|
||||
|
||||
const chmodSupported = runtime.GOOS != "windows"
|
||||
|
||||
// backupFile writes data to a new file named filename<number> with permissions perm,
|
||||
// with <number randomly chosen such that the file name is unique. backupFile returns
|
||||
// the chosen file name.
|
||||
// copy from golang/cmd/gofmt
|
||||
func backupFile(filename string, data []byte, perm os.FileMode) (string, error) {
|
||||
// create backup file
|
||||
f, err := ioutil.TempFile(filepath.Dir(filename), filepath.Base(filename))
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if chmodSupported {
|
||||
_ = f.Chmod(perm)
|
||||
}
|
||||
|
||||
// write data to backup file
|
||||
_, err = f.Write(data)
|
||||
if err1 := f.Close(); err == nil {
|
||||
err = err1
|
||||
}
|
||||
return f.Name(), err
|
||||
}
|
||||
34
vendor/github.com/swaggo/swag/go.mod
generated
vendored
Normal file
34
vendor/github.com/swaggo/swag/go.mod
generated
vendored
Normal file
@@ -0,0 +1,34 @@
|
||||
module github.com/swaggo/swag
|
||||
|
||||
go 1.17
|
||||
|
||||
require (
|
||||
github.com/KyleBanks/depth v1.2.1
|
||||
github.com/agiledragon/gomonkey/v2 v2.3.1
|
||||
github.com/ghodss/yaml v1.0.0
|
||||
github.com/go-openapi/spec v0.20.4
|
||||
github.com/otiai10/copy v1.7.0
|
||||
github.com/stretchr/testify v1.7.0
|
||||
github.com/urfave/cli/v2 v2.3.0
|
||||
golang.org/x/tools v0.1.7
|
||||
)
|
||||
|
||||
require (
|
||||
github.com/PuerkitoBio/purell v1.1.1 // indirect
|
||||
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
|
||||
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d // indirect
|
||||
github.com/davecgh/go-spew v1.1.1 // indirect
|
||||
github.com/go-openapi/jsonpointer v0.19.5 // indirect
|
||||
github.com/go-openapi/jsonreference v0.19.6 // indirect
|
||||
github.com/go-openapi/swag v0.19.15 // indirect
|
||||
github.com/josharian/intern v1.0.0 // indirect
|
||||
github.com/mailru/easyjson v0.7.6 // indirect
|
||||
github.com/pmezard/go-difflib v1.0.0 // indirect
|
||||
github.com/russross/blackfriday/v2 v2.0.1 // indirect
|
||||
github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
|
||||
golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d // indirect
|
||||
golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e // indirect
|
||||
golang.org/x/text v0.3.7 // indirect
|
||||
gopkg.in/yaml.v2 v2.4.0 // indirect
|
||||
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 // indirect
|
||||
)
|
||||
109
vendor/github.com/swaggo/swag/go.sum
generated
vendored
Normal file
109
vendor/github.com/swaggo/swag/go.sum
generated
vendored
Normal file
@@ -0,0 +1,109 @@
|
||||
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
|
||||
github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
|
||||
github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
|
||||
github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tNFfI=
|
||||
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
|
||||
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M=
|
||||
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
|
||||
github.com/agiledragon/gomonkey/v2 v2.3.1 h1:k+UnUY0EMNYUFUAQVETGY9uUTxjMdnUkP0ARyJS1zzs=
|
||||
github.com/agiledragon/gomonkey/v2 v2.3.1/go.mod h1:ap1AmDzcVOAz1YpeJ3TCzIgstoaWLA6jbbgxfB4w2iY=
|
||||
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d h1:U+s90UTSYgptZMwQh2aRr3LuazLJIa+Pg3Kc1ylSYVY=
|
||||
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
|
||||
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk=
|
||||
github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
|
||||
github.com/go-openapi/jsonpointer v0.19.3/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
|
||||
github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
|
||||
github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
|
||||
github.com/go-openapi/jsonreference v0.19.6 h1:UBIxjkht+AWIgYzCDSv2GN+E/togfwXUJFRTWhl2Jjs=
|
||||
github.com/go-openapi/jsonreference v0.19.6/go.mod h1:diGHMEHg2IqXZGKxqyvWdfWU/aim5Dprw5bqpKkTvns=
|
||||
github.com/go-openapi/spec v0.20.4 h1:O8hJrt0UMnhHcluhIdUgCLRWyM2x7QkBXRvOs7m+O1M=
|
||||
github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7FOEWeq8I=
|
||||
github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
|
||||
github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
|
||||
github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
|
||||
github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
|
||||
github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
|
||||
github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
|
||||
github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
|
||||
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
|
||||
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
|
||||
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
|
||||
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
|
||||
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
|
||||
github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
|
||||
github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
|
||||
github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA=
|
||||
github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
|
||||
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
|
||||
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
|
||||
github.com/otiai10/copy v1.7.0 h1:hVoPiN+t+7d2nzzwMiDHPSOogsWAStewq3TwU05+clE=
|
||||
github.com/otiai10/copy v1.7.0/go.mod h1:rmRl6QPdJj6EiUqXQ/4Nn2lLXoNQjFCQbbNrxgc/t3U=
|
||||
github.com/otiai10/curr v0.0.0-20150429015615-9b4961190c95/go.mod h1:9qAhocn7zKJG+0mI8eUu6xqkFDYS2kb2saOteoSB3cE=
|
||||
github.com/otiai10/curr v1.0.0/go.mod h1:LskTG5wDwr8Rs+nNQ+1LlxRjAtTZZjtJW4rMXl6j4vs=
|
||||
github.com/otiai10/mint v1.3.0/go.mod h1:F5AjcsTsWUqX+Na9fpHb52P8pcRX2CI6A3ctIT91xUo=
|
||||
github.com/otiai10/mint v1.3.3 h1:7JgpsBaN0uMkyju4tbYHu0mnM55hNKVYLsXmwr15NQI=
|
||||
github.com/otiai10/mint v1.3.3/go.mod h1:/yxELlJQ0ufhjUwhshSj+wFjZ78CnZ48/1wtmBH1OTc=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q=
|
||||
github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
|
||||
github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
|
||||
github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
|
||||
github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
|
||||
github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
|
||||
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/urfave/cli/v2 v2.3.0 h1:qph92Y649prgesehzOrQjdWyxFOp/QVM+6imKHad91M=
|
||||
github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
|
||||
github.com/yuin/goldmark v1.4.0/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
|
||||
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
|
||||
golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
|
||||
golang.org/x/mod v0.4.2 h1:Gz96sIWK3OalVv/I/qNygP42zyoKp3xptRVCWRFEBvo=
|
||||
golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
|
||||
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
|
||||
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
|
||||
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
|
||||
golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
|
||||
golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d h1:20cMwl2fHAzkJMEA+8J4JgqBQcQGzbisXo31MIeenXI=
|
||||
golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
|
||||
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
|
||||
golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
|
||||
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
|
||||
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
|
||||
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
|
||||
golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
|
||||
golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
|
||||
golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e h1:WUoyKPm6nCo1BnNUvPGnFG3T5DUVem42yDJZZ4CNxMA=
|
||||
golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
|
||||
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
|
||||
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
|
||||
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
|
||||
golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk=
|
||||
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
|
||||
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
|
||||
golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
|
||||
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
|
||||
golang.org/x/tools v0.1.7 h1:6j8CgantCy3yc8JGBqkDLMKWqZ0RDU2g1HVgacojGWQ=
|
||||
golang.org/x/tools v0.1.7/go.mod h1:LGqMHiF4EqQNHR1JncWGqT5BVaXmza+X+BDGol+dOxo=
|
||||
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
|
||||
golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
|
||||
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
|
||||
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU=
|
||||
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
|
||||
gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
|
||||
gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
|
||||
gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 h1:tQIYjPdBoyREyB9XMu+nnTclpTYkz2zFM+lzLJFO4gQ=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
21
vendor/github.com/swaggo/swag/license
generated
vendored
Normal file
21
vendor/github.com/swaggo/swag/license
generated
vendored
Normal file
@@ -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.
|
||||
1075
vendor/github.com/swaggo/swag/operation.go
generated
vendored
Normal file
1075
vendor/github.com/swaggo/swag/operation.go
generated
vendored
Normal file
File diff suppressed because it is too large
Load Diff
336
vendor/github.com/swaggo/swag/packages.go
generated
vendored
Normal file
336
vendor/github.com/swaggo/swag/packages.go
generated
vendored
Normal file
@@ -0,0 +1,336 @@
|
||||
package swag
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
goparser "go/parser"
|
||||
"go/token"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"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
|
||||
}
|
||||
|
||||
// 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),
|
||||
}
|
||||
}
|
||||
|
||||
// CollectAstFile collect ast.file.
|
||||
func (pkgs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File) error {
|
||||
if pkgs.files == nil {
|
||||
pkgs.files = make(map[*ast.File]*AstFileInfo)
|
||||
}
|
||||
|
||||
if pkgs.packages == nil {
|
||||
pkgs.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
|
||||
}
|
||||
|
||||
pd, ok := pkgs.packages[packageDir]
|
||||
if ok {
|
||||
// return without storing the file if it already exists
|
||||
_, exists := pd.Files[path]
|
||||
if exists {
|
||||
return nil
|
||||
}
|
||||
pd.Files[path] = astFile
|
||||
} else {
|
||||
pkgs.packages[packageDir] = &PackageDefinitions{
|
||||
Name: astFile.Name.Name,
|
||||
Files: map[string]*ast.File{path: astFile},
|
||||
TypeDefinitions: make(map[string]*TypeSpecDef),
|
||||
}
|
||||
}
|
||||
|
||||
pkgs.files[astFile] = &AstFileInfo{
|
||||
File: astFile,
|
||||
Path: path,
|
||||
PackagePath: packageDir,
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// RangeFiles for range the collection of ast.File in alphabetic order.
|
||||
func rangeFiles(files map[*ast.File]*AstFileInfo, handle func(filename string, file *ast.File) error) error {
|
||||
sortedFiles := make([]*AstFileInfo, 0, len(files))
|
||||
for _, info := range files {
|
||||
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.Path, info.File)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// ParseTypes parse types
|
||||
// @Return parsed definitions.
|
||||
func (pkgs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error) {
|
||||
parsedSchemas := make(map[*TypeSpecDef]*Schema)
|
||||
for astFile, info := range pkgs.files {
|
||||
pkgs.parseTypesFromFile(astFile, info.PackagePath, parsedSchemas)
|
||||
}
|
||||
return parsedSchemas, nil
|
||||
}
|
||||
|
||||
func (pkgs *PackagesDefinitions) parseTypesFromFile(astFile *ast.File, packagePath string, parsedSchemas map[*TypeSpecDef]*Schema) {
|
||||
for _, astDeclaration := range astFile.Decls {
|
||||
if generalDeclaration, ok := astDeclaration.(*ast.GenDecl); ok && 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 pkgs.uniqueDefinitions == nil {
|
||||
pkgs.uniqueDefinitions = make(map[string]*TypeSpecDef)
|
||||
}
|
||||
|
||||
fullName := typeSpecDef.FullName()
|
||||
anotherTypeDef, ok := pkgs.uniqueDefinitions[fullName]
|
||||
if ok {
|
||||
if typeSpecDef.PkgPath == anotherTypeDef.PkgPath {
|
||||
continue
|
||||
} else {
|
||||
delete(pkgs.uniqueDefinitions, fullName)
|
||||
}
|
||||
} else {
|
||||
pkgs.uniqueDefinitions[fullName] = typeSpecDef
|
||||
}
|
||||
|
||||
if pkgs.packages[typeSpecDef.PkgPath] == nil {
|
||||
pkgs.packages[typeSpecDef.PkgPath] = &PackageDefinitions{
|
||||
Name: astFile.Name.Name,
|
||||
TypeDefinitions: map[string]*TypeSpecDef{typeSpecDef.Name(): typeSpecDef},
|
||||
}
|
||||
} else if _, ok = pkgs.packages[typeSpecDef.PkgPath].TypeDefinitions[typeSpecDef.Name()]; !ok {
|
||||
pkgs.packages[typeSpecDef.PkgPath].TypeDefinitions[typeSpecDef.Name()] = typeSpecDef
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (pkgs *PackagesDefinitions) findTypeSpec(pkgPath string, typeName string) *TypeSpecDef {
|
||||
if pkgs.packages == nil {
|
||||
return nil
|
||||
}
|
||||
pd, found := pkgs.packages[pkgPath]
|
||||
if found {
|
||||
typeSpec, ok := pd.TypeDefinitions[typeName]
|
||||
if ok {
|
||||
return typeSpec
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (pkgs *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 {
|
||||
pkgs.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
|
||||
// @fuzzy search for the package path that the last part matches the @pkg if true
|
||||
// @return the package path of a package of @pkg.
|
||||
func (pkgs *PackagesDefinitions) findPackagePathFromImports(pkg string, file *ast.File, fuzzy bool) string {
|
||||
if file == nil {
|
||||
return ""
|
||||
}
|
||||
|
||||
if strings.ContainsRune(pkg, '.') {
|
||||
pkg = strings.Split(pkg, ".")[0]
|
||||
}
|
||||
|
||||
hasAnonymousPkg := false
|
||||
|
||||
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 {
|
||||
if imp.Name != nil {
|
||||
if imp.Name.Name == pkg {
|
||||
return strings.Trim(imp.Path.Value, `"`)
|
||||
}
|
||||
if imp.Name.Name == "_" {
|
||||
hasAnonymousPkg = true
|
||||
}
|
||||
|
||||
continue
|
||||
}
|
||||
if pkgs.packages != nil {
|
||||
path := strings.Trim(imp.Path.Value, `"`)
|
||||
if fuzzy {
|
||||
if matchLastPathPart(path) {
|
||||
return path
|
||||
}
|
||||
} else if pd, ok := pkgs.packages[path]; ok && pd.Name == pkg {
|
||||
return path
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// match unnamed package
|
||||
if hasAnonymousPkg && pkgs.packages != nil {
|
||||
for _, imp := range file.Imports {
|
||||
if imp.Name == nil {
|
||||
continue
|
||||
}
|
||||
if imp.Name.Name == "_" {
|
||||
path := strings.Trim(imp.Path.Value, `"`)
|
||||
if fuzzy {
|
||||
if matchLastPathPart(path) {
|
||||
return path
|
||||
}
|
||||
} else if pd, ok := pkgs.packages[path]; ok && pd.Name == pkg {
|
||||
return path
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return ""
|
||||
}
|
||||
|
||||
// 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 (pkgs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File, parseDependency bool) *TypeSpecDef {
|
||||
if IsGolangPrimitiveType(typeName) {
|
||||
return nil
|
||||
}
|
||||
if file == nil { // for test
|
||||
return pkgs.uniqueDefinitions[typeName]
|
||||
}
|
||||
|
||||
parts := strings.Split(typeName, ".")
|
||||
if len(parts) > 1 {
|
||||
isAliasPkgName := func(file *ast.File, pkgName string) bool {
|
||||
if file != nil && file.Imports != nil {
|
||||
for _, pkg := range file.Imports {
|
||||
if pkg.Name != nil && pkg.Name.Name == pkgName {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
if !isAliasPkgName(file, parts[0]) {
|
||||
typeDef, ok := pkgs.uniqueDefinitions[typeName]
|
||||
if ok {
|
||||
return typeDef
|
||||
}
|
||||
}
|
||||
pkgPath := pkgs.findPackagePathFromImports(parts[0], file, false)
|
||||
if len(pkgPath) == 0 {
|
||||
// check if the current package
|
||||
if parts[0] == file.Name.Name {
|
||||
pkgPath = pkgs.files[file].PackagePath
|
||||
} else if parseDependency {
|
||||
// take it as an external package, needs to be loaded
|
||||
if pkgPath = pkgs.findPackagePathFromImports(parts[0], file, true); len(pkgPath) > 0 {
|
||||
if err := pkgs.loadExternalPackage(pkgPath); err != nil {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return pkgs.findTypeSpec(pkgPath, parts[1])
|
||||
}
|
||||
|
||||
typeDef, ok := pkgs.uniqueDefinitions[fullTypeName(file.Name.Name, typeName)]
|
||||
if ok {
|
||||
return typeDef
|
||||
}
|
||||
|
||||
typeDef = pkgs.findTypeSpec(pkgs.files[file].PackagePath, typeName)
|
||||
if typeDef != nil {
|
||||
return typeDef
|
||||
}
|
||||
|
||||
for _, imp := range file.Imports {
|
||||
if imp.Name != nil && imp.Name.Name == "." {
|
||||
typeDef := pkgs.findTypeSpec(strings.Trim(imp.Path.Value, `"`), typeName)
|
||||
if typeDef != nil {
|
||||
return typeDef
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
1480
vendor/github.com/swaggo/swag/parser.go
generated
vendored
Normal file
1480
vendor/github.com/swaggo/swag/parser.go
generated
vendored
Normal file
File diff suppressed because it is too large
Load Diff
194
vendor/github.com/swaggo/swag/schema.go
generated
vendored
Normal file
194
vendor/github.com/swaggo/swag/schema.go
generated
vendored
Normal file
@@ -0,0 +1,194 @@
|
||||
package swag
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"strings"
|
||||
|
||||
"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"
|
||||
// ANY represent a any value.
|
||||
ANY = "any"
|
||||
// NIL represent a empty value.
|
||||
NIL = "nil"
|
||||
)
|
||||
|
||||
// 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
|
||||
}
|
||||
|
||||
// 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 ""
|
||||
}
|
||||
|
||||
// TypeDocName get alias from comment '// @name ', otherwise the original type name to display in doc.
|
||||
func TypeDocName(pkgName string, spec *ast.TypeSpec) string {
|
||||
if spec != nil {
|
||||
if spec.Comment != nil {
|
||||
for _, comment := range spec.Comment.List {
|
||||
texts := strings.Split(strings.TrimSpace(strings.TrimLeft(comment.Text, "/")), " ")
|
||||
if len(texts) > 1 && strings.ToLower(texts[0]) == "@name" {
|
||||
return texts[1]
|
||||
}
|
||||
}
|
||||
}
|
||||
if spec.Name != nil {
|
||||
return fullTypeName(strings.Split(pkgName, ".")[0], spec.Name.Name)
|
||||
}
|
||||
}
|
||||
|
||||
return pkgName
|
||||
}
|
||||
|
||||
// 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
|
||||
}
|
||||
}
|
||||
54
vendor/github.com/swaggo/swag/spec.go
generated
vendored
Normal file
54
vendor/github.com/swaggo/swag/spec.go
generated
vendored
Normal file
@@ -0,0 +1,54 @@
|
||||
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
|
||||
}
|
||||
|
||||
// ReadDoc parses SwaggerTemplate into swagger document.
|
||||
func (i *Spec) ReadDoc() string {
|
||||
i.Description = strings.Replace(i.Description, "\n", "\\n", -1)
|
||||
|
||||
t, err := 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
|
||||
str := strings.Replace(v.(string), "\t", "\\t", -1)
|
||||
// replace " with \", and if that results in \\", replace that with \\\"
|
||||
str = strings.Replace(str, "\"", "\\\"", -1)
|
||||
return strings.Replace(str, "\\\\\"", "\\\\\\\"", -1)
|
||||
},
|
||||
}).Parse(i.SwaggerTemplate)
|
||||
if err != nil {
|
||||
return i.SwaggerTemplate
|
||||
}
|
||||
|
||||
var tpl bytes.Buffer
|
||||
if err = t.Execute(&tpl, i); err != nil {
|
||||
return i.SwaggerTemplate
|
||||
}
|
||||
|
||||
return tpl.String()
|
||||
}
|
||||
|
||||
// InstanceName returns Spec instance name.
|
||||
func (i *Spec) InstanceName() string {
|
||||
return i.InfoInstanceName
|
||||
}
|
||||
61
vendor/github.com/swaggo/swag/swagger.go
generated
vendored
Normal file
61
vendor/github.com/swaggo/swag/swagger.go
generated
vendored
Normal file
@@ -0,0 +1,61 @@
|
||||
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
|
||||
}
|
||||
|
||||
// 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
|
||||
}
|
||||
69
vendor/github.com/swaggo/swag/types.go
generated
vendored
Normal file
69
vendor/github.com/swaggo/swag/types.go
generated
vendored
Normal file
@@ -0,0 +1,69 @@
|
||||
package swag
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
|
||||
"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
|
||||
|
||||
// path of package starting from under ${GOPATH}/src or from module path in go.mod
|
||||
PkgPath string
|
||||
}
|
||||
|
||||
// Name the name of the typeSpec.
|
||||
func (t *TypeSpecDef) Name() string {
|
||||
if t.TypeSpec != nil {
|
||||
return t.TypeSpec.Name.Name
|
||||
}
|
||||
|
||||
return ""
|
||||
}
|
||||
|
||||
// FullName full name of the typeSpec.
|
||||
func (t *TypeSpecDef) FullName() string {
|
||||
return fullTypeName(t.File.Name.Name, t.TypeSpec.Name.Name)
|
||||
}
|
||||
|
||||
// FullPath of the typeSpec.
|
||||
func (t *TypeSpecDef) FullPath() string {
|
||||
return t.PkgPath + "." + t.Name()
|
||||
}
|
||||
|
||||
// AstFileInfo information of an ast.File.
|
||||
type AstFileInfo struct {
|
||||
// File ast.File
|
||||
File *ast.File
|
||||
|
||||
// Path the path of the ast.File
|
||||
Path string
|
||||
|
||||
// PackagePath package import path of the ast.File
|
||||
PackagePath string
|
||||
}
|
||||
|
||||
// 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
|
||||
|
||||
// package name
|
||||
Name string
|
||||
}
|
||||
4
vendor/github.com/swaggo/swag/version.go
generated
vendored
Normal file
4
vendor/github.com/swaggo/swag/version.go
generated
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
package swag
|
||||
|
||||
// Version of swag.
|
||||
const Version = "v1.8.0"
|
||||
Reference in New Issue
Block a user