Скачать swag - Скачать исходный код swag

раскачиваться

? Английский ∙ 简体中文 ∙ Португас

Статус сборки

Swag Converts Go Аннотации в Swagger Documentation 2.0. Мы создали различные плагины для популярных веб -карт GO. Это позволяет быстро интегрироваться с существующим проектом GO (с помощью пользовательского интерфейса Swagger).

Содержимое

Начиная
Поддерживаемые веб -фреймворки
Как использовать его с джином
Форматер добычи
Статус реализации
Формат декларативных комментариев
- Общая информация API
- Операция API
- Безопасность
Примеры
- Описания по нескольким линиям
- Пользовательская структура с типом массива
- Объявление структуры функции
- Состав модели в ответ
  - Добавить заголовки запросов
- Добавьте заголовки ответов
- Используйте несколько параметров пути
- Пример значения структуры
- Схема пример тела
- Описание структуры
- Используйте тег SwaggerType для поддерживаемого пользовательского типа
- Используйте глобальные переопределения, чтобы поддержать пользовательский тип
- Используйте тег Swaggerignore, чтобы исключить поле
- Добавить информацию о расширении в поле struct
- Переименовать модель для отображения
- Как использовать аннотации безопасности
- Добавить описание для элементов перечисления
- Генерировать только конкретные типы файлов DOCS
- Как использовать Go общие типы
О проекте

Начиная

Добавьте комментарии к вашему исходному коду API, см. Формат декларативных комментариев.
Установите SWAG с помощью:

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

Чтобы построить из источника, вам нужно идти (1.19 или новее).

В качестве альтернативы вы можете запустить изображение Docker:

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

Или загрузите предварительно скомпилированный бинар со страницы выпуска.

Запустите swag init в корневой папке проекта, которая содержит файл main.go Это проанализирует ваши комментарии и генерирует необходимые файлы (папка docs и docs/docs.go ).

swag init

Убедитесь, что импортируйте сгенерированные docs/docs.go чтобы ваша конкретная конфигурация была init . Если ваши общие аннотации API не живут в main.go , вы можете сообщить Swag с флагом -g .

 import _ "example-module-name/docs"

swag init -g http/api.go

(Необязательно) Используйте формат swag fmt Комментарий SWAG. (Пожалуйста, перейдите на последнюю версию)

swag fmt

Swag Cli

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

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

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

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

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

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

Поддерживаемые веб -фреймворки

Джин
эхо
Буффало
net/http
Горилла/MUX
go-chi/chi
фламинго
волокно
Атреуго
герц

Как использовать его с джином

Найдите пример исходного кода здесь.

Завершите шаги в начале работы

После использования swag init для создания DAGGER 2.0 DOCS импортируйте следующие пакеты:

 import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

Добавьте общие аннотации API в код main.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  [email protected]

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

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

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
func main () {
	r := gin . Default ()

	c := controller . NewController ()

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

Кроме того, некоторая общая информация API может быть установлена динамически. Сгенерированный пакет кода docs экспортирует переменную SwaggerInfo , которую мы можем использовать для установки заголовка, описания, версии, хоста и базового пути. Пример с использованием джина:

 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  [email protected]

// @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 ()
}

Добавить аннотации операции API в код controller

 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 )
}
//...

 swag init

Запустите свое приложение и просмотрите http: // localhost: 8080/swagger/index.html. Вы увидите документы API Swagger 2.0, как показано ниже:

Форматер добычи

Комментарии SWAG могут быть автоматически отформатированы, как «Go FMT». Найдите результат форматирования здесь.

Использование:

swag fmt

Исключить папку:

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

При использовании swag fmt вам необходимо убедиться, что у вас есть комментарий DOC для функции, чтобы обеспечить правильное форматирование. Это связано с тем, что swag fmt Compenting Swag Comments с вкладками, которые разрешены только после стандартного комментария DOC.

Например, используйте

 // ListAccounts lists all existing accounts
//
//  @Summary      List accounts
//  @Description  get accounts
//  @Tags         accounts
//  @Accept       json
//  @Produce      json
//  @Param        q    query     string  false  "name search by q"  Format(email)
//  @Success      200  {array}   model.Account
//  @Failure      400  {object}  httputil.HTTPError
//  @Failure      404  {object}  httputil.HTTPError
//  @Failure      500  {object}  httputil.HTTPError
//  @Router       /accounts [get]
func ( c * Controller ) ListAccounts ( ctx * gin. Context ) {

Статус реализации

Swagger 2.0 документ

Формат декларативных комментариев

Общая информация API

Пример Celler/Main.go

аннотация	описание	пример
заголовок	Необходимый. Название приложения.	// @title Swagger Пример API
версия	Необходимый. Предоставляет версию API приложения.	// @version 1.0
описание	Краткое описание приложения.	// @Description Это пример сервера Celler Server.
tag.name	Название тега.	// @Tag.name Это имя тега
tag.description	Описание тега	// @Tag.description Cool Описание
tag.docs.url	URL внешней документации тега	// @Tag.docs.url https://example.com
tag.docs.description	Описание внешней документации тега	// @tag.docs.description Лучший пример документации
Термины	Условия обслуживания для API.	// @termsofservice http://swagger.io/terms/
contact.name	Контактная информация для открытого API.	// @contact.name Поддержка API
Contact.url	URL, указывающий на контактную информацию. Должен быть в формате URL.	// @contact.url http://www.swagger.io/support
Contact.mail	Адрес электронной почты контактного лица/организации. Должен быть в формате адреса электронной почты.	// @contact.email [email protected]
Лицензия	Необходимый. Имя лицензии, используемое для API.	// @License.name Apache 2.0
лицензия	URL -адрес лицензии, используемой для API. Должен быть в формате URL.	// @License.url http://www.apache.org/licenses/license-2.0.html
хозяин	Хост (имя или IP), обслуживающий API.	// @host Localhost: 8080
Базовый	Базовый путь, по которому подается API.	// @basepath/api/v1
принимать	Список типов MIME, которые API могут потреблять. Обратите внимание, что принятие влияет только на операции с помощью корпуса запроса, такого как Post, Pul и Patch. Значение должно быть так, как описано в типах MIME.	// @Accept json
производить	Список типов MIME, которые могут производить API. Значение должно быть так, как описано в типах MIME.	// @produce json
Query.collection.format	Формат параметра по умолчанию (массив) в запросе, перечисления: CSV, Multi, Pipes, TSV, SSV. Если не установлено, CSV является дефолтом.	// @Query.collection.format multi
схемы	Протокол переноса для операции, которая разделена пространствами.	// @schemes http https
Externaldocs.description	Описание внешнего документа.	// @externaldocs.description openapi
externaldocs.url	URL внешнего документа.	// @externaldocs.url https://swagger.io/resources/open-api/
x-name	Ключ расширения должен быть начат с X- и принять только значение JSON	// @x-example-key {"key": "value"}

Используя описания отметки

Когда короткой строки в вашей документации недостаточно, или вам нужны изображения, примеры кода и такие вещи, вы можете использовать описания уценки. Для использования описания отметки используйте следующие аннотации.

аннотация	описание	пример
заголовок	Необходимый. Название приложения.	// @title Swagger Пример API
версия	Необходимый. Предоставляет версию API приложения.	// @version 1.0
Описание.markdown	Краткое описание приложения. Проанализируется из файла api.md. Это альтернатива @description	// @description.markdown Не требуется значение, это анализирует описание из api.md
tag.name	Название тега.	// @Tag.name Это имя тега
tag.description.markdown	Описание тега Это альтернатива tag.description. Описание будет считан из файла с именем, как Tagname.md	// @tag.description.markdown
tag.x-name	Ключ для расширения должен быть начат с x- и принять только строковое значение	// @x-example-key

Операция API

Пример Celler/Controller

аннотация	описание
описание	Многословное объяснение операционного поведения.
Описание.markdown	Краткое описание приложения. Описание будет прочитано из файла. Например, `@description.markdown details` загружат `details.md`
идентификатор	Уникальная строка, используемая для идентификации операции. Должен быть уникальным среди всех операций API.
теги	Список тегов для каждой операции API, которая разделена запятыми.
краткое содержание	Краткое краткое изложение того, что делает операция.
принимать	Список типов MIME, которые API могут потреблять. Обратите внимание, что принятие влияет только на операции с помощью корпуса запроса, такого как Post, Pul и Patch. Значение должно быть так, как описано в типах MIME.
производить	Список типов MIME, которые могут производить API. Значение должно быть так, как описано в типах MIME.
парамет	Параметры, которые разделены пространствами. `param name` , `param type` , `data type` , `is mandatory?` , атрибут `comment` `attribute(optional)`
безопасность	Безопасность для каждой операции API.
успех	Ответ успеха, который разделен пробелами. `return code or default` , `{param type}` , `data type` , `comment`
отказ	Ответ отказа, который разделен пробелами. `return code or default` , `{param type}` , `data type` , `comment`
ответ	Так же, как `success` и `failure`
заголовок	Заголовок в ответ, который разделен пространствами. `return code` , `{param type}` , `data type` , `comment`
маршрутизатор	Определение пути, которое разделено пространствами. `path` , `[httpMethod]`
устаревший	Так же, как маршрутизатор, но устарел.
x-name	Ключ расширения должен быть начат с X- и принять только значение JSON.
X-Codesample	Необязательное использование отметки. Возьмите `file` как параметр. Затем это будет искать файл с именем, как резюме в данной папке.
устарел	Марк конечная точка как устарела.

Типы мима

swag принимает все типы MIME, которые находятся в правильном формате, то есть совместно */* . Кроме того, swag также принимает псевдонимы для некоторых типов парионного падения следующим образом:

Псевдоним	Тип мима
json	Приложение/JSON
XML	Текст/XML
простой	текст/равнина
HTML	Текст/HTML
MPFD	Multipart/Form-Data
X-WWW-FORM-URLENCODE	Приложение/X-WWW-FORM-URLENCODED
json-api	Приложение/vnd.api+json
JSON-Stream	приложение/x-json-stream
октет-поток	Приложение/октет
пнн	Изображение/PNG
JPEG	Изображение/JPEG
гифка	Изображение/GIF

Param Type

запрос
путь
заголовок
тело
FormData

Тип данных

String (String)
Integer (int, uint, uint32, uint64)
номер (float32)
логический (Bool)
Файл (тип данных параметра при загрузке)
Пользователь определенный struct

Безопасность

аннотация	описание	параметры	пример
SecurityDefinitions.basic	Основная аут.		// @SecurityDefinitions.basic Basicauth
SecurityDefinitions.apikey	API Key Auth.	в, имя, описание	// @SecurityDefinitions.apikey apikeyauth
SecurityDefinitions.oauth2.application	Oauth2 приложение Auth.	Tokenurl, Scope, описание	// @SecurityDefinitions.oauth2.application oauth2application
SecurityDefinitions.oauth2.implicit	Oauth2 неявная аут.	AuthorizationUrl, Scope, описание	// @SecurityDefinitions.oauth2.implicite oauth2implicit
SecurityDefinitions.oauth2.password	OAuth2 Password Auth.	Tokenurl, Scope, описание	// @SecurityDefinitions.oauth2.password oauth2password
SecurityDefinitions.oauth2.accesscode	OAUTH2 Код доступа Auth.	Tokenurl, AuthorizationUrl, Scope, описание	// @SecurityDefinitions.oauth2.accesscode oauth2accesscode

параметры аннотации	пример
в	// @In заголовок
имя	// @name Авторизация
Tokenurl	// @tokenurl https://example.com/oauth/token
AuthorizationUrl	// @AuthorizationUrl https://example.com/oauth/authorize
Scope.hoge	// @scope.write Grants Access Access
описание	// @description oauth защищает конечные точки нашей организации

Атрибут

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

Это также работает для поля структуры:

 type Foo struct {
    Bar string `minLength:"4" maxLength:"16" example:"random string"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux [] string `enums:"foo,bar,baz"`
}

Доступный

Имя поля	Тип	Описание
проверять	`string`	Определяет проверку для параметра. Возможные значения: `required,optional` .
по умолчанию	*	Объявляет значение параметра, которое сервер будет использовать, если ни один не будет предоставлен, например, «счет» для управления количеством результатов на страницу может по умолчанию, если не поставляется клиентом в запросе. (Примечание: «по умолчанию» не имеет значения для необходимых параметров.) См. Https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. В отличие от схемы JSON, это значение должно соответствовать определенному `type` для этого параметра.
максимум	`number`	См.
минимум	`number`	См.
несколько	`number`	См.
MaxLength	`integer`	См.
Minlength	`integer`	См.
перечисление	[*]	См.
формат	`string`	Расширенный формат для ранее упомянутого `type` . См. Форматы типа данных для получения более подробной информации.
CollectionFormat	`string`	Определяет формат массива, если используется массив типов. Возможные значения: `csv` - Запятая отделена значения `foo,bar` . `ssv` - пространство разделенное значения `foo bar` . `tsv` - TAB SDATED значения `footbar` . `pipes` - Труба отделенные значения `foo\|bar` . `multi` - соответствует нескольким экземплярам параметров вместо нескольких значений для одного экземпляра `foo=bar&foo=baz` . Это действительно только для параметров `in` «запросе» или «FormData». Значение по умолчанию - `csv` .
пример	*	Объявляет пример значения параметра
расширения	`string`	Добавить расширение в параметры.

Будущее

Имя поля	Тип	Описание
шаблон	`string`	См.
максима	`integer`	См.
Minitiems	`integer`	См.
уникальные	`boolean`	См.

Примеры

Описания по нескольким линиям

Вы можете добавить описания, охватывающие несколько строк в общее описание API или определения маршрутов, такие как SO:

 // @description This is the first line
// @description This is the second line
// @description And so forth.

Пользовательская структура с типом массива

 // @Success 200 {array} model.Account <-- This is a user defined struct.

 package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

Объявление структуры функции

Вы можете объявить свои структуры ответа на запрос внутри корпуса функции. Вы должны следовать соглашению о именовании <package-name>.<function-name>.<struct-name> .

 package main

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

	type response struct {
		ResponseField string
	}
}

Состав модели в ответ

 // JSONResult's data field will be overridden by the specific type proto.Order
@ success 200 { object } jsonresult. JSONResult { data = proto . Order } "desc"

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

type Order struct { //in `proto` package
    Id  uint            `json:"id"`
    Data  interface {}   `json:"data"`
}

Также поддержка массива объектов и примитивных типов в качестве вложенного ответа

@ success 200 { object } jsonresult. JSONResult { data = []proto. Order } "desc"
@ success 200 { object } jsonresult. JSONResult { data = string } "desc"
@ success 200 { object } jsonresult. JSONResult { data = [] string } "desc"

переопределение нескольких полей. Поле будет добавлено, если не существует

@ success 200 { object } jsonresult. JSONResult { data1 = string , data2 = [] string , data3 = proto . Order , data4 = []proto. Order } "desc"

Переходящие глубокоуровневые поля

 type DeepObject struct { //in `proto` package
	...
}
@ success 200 { object } jsonresult. JSONResult { data1 = proto. Order { data = proto . DeepObject }, data2 = []proto. Order { data = []proto. DeepObject }} "desc"

Добавить запрос ответа

 // @Param        X-MyHeader	  header    string    true   	"MyHeader must be set for valid response"
// @Param        X-API-VERSION    header    string    true   	"API version eg.: 1.0"

Добавьте заголовки ответов

 // @Success      200              {string}  string    "ok"
// @failure      400              {string}  string    "error"
// @response     default          {string}  string    "other error"
// @Header       200              {string}  Location  "/entity/1"
// @Header       200,400,default  {string}  Token     "token"
// @Header       all              {string}  Token2    "token2"

Используйте несколько параметров пути

 /// ...
// @Param group_id   path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

Добавьте несколько путей

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

Пример значения структуры

 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"`
}

Схема пример тела

 // @Param email body string true "message/rfc822" SchemaExample(Subject: TestmailrnrnBody Messagern)

Описание структуры

 // 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 Сиарсер обрабатывает только комментарии struct, начиная с атрибута @Description . Но он пишет все полевые комментарии Struct как есть.

Итак, сгенерировал Swagger Doc следующим образом:

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

Используйте тег SwaggerType для поддерживаемого пользовательского типа

#201

 type TimestampTime struct {
    time. Time
}

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

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

type Account struct {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql. NullInt64 `json:"id" swaggertype:"integer"`

    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

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

#379

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

сгенерировал Swagger DOC следующим образом:

 "api.MyBinding" : {
  "type" :" object ",
  "properties" :{
    "crt" :{
      "type" :" string ",
      "format" :" base64 ",
      "example" :" U3dhZ2dlciByb2Nrcw == "
    },
    "key" :{
      "type" :" string ",
      "format" :" base64 ",
      "example" :" U3dhZ2dlciByb2Nrcw == "
    }
  }
}

Используйте глобальные переопределения, чтобы поддержать пользовательский тип

Если вы используете сгенерированные файлы, теги swaggertype или swaggerignore могут быть невозможны.

Пропустив картирование, чтобы добывать с --overridesFile вы можете сказать Swag использовать один тип вместо другого, где бы он ни появился. По умолчанию, если файл .swaggo присутствует в текущем каталоге, он будет использоваться.

Go Code:

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

.swaggo :

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

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

Возможными директивами являются комментарии (начиная с // ), replace path/to/a.type path/to/b.type и skip path/to/a.type .

(Обратите внимание, что полный путь к любым названным типам должны быть предоставлены, чтобы предотвратить проблемы, когда несколько пакетов определяют тип с тем же именем)

Рендерировано:

 "types.MyStruct" : {
  "id" : "integer"
}

Используйте тег Swaggerignore, чтобы исключить поле

 type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}

Добавить информацию о расширении в поле struct

 type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}

генерируйте Swagger DOC следующим образом:

 "Account" : {
    "type" : "object" ,
    "properties" : {
        "id" : {
            "type" : "string" ,
            "x-nullable" : true ,
            "x-abc" : "def" ,
            "x-omitempty" : false
        }
    }
}

Переименовать модель для отображения

 type Resp struct {
	Code int
} //@name Response

Как использовать аннотации безопасности

Общая информация API.

 // @securityDefinitions.basic BasicAuth

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

Каждая операция API.

 // @Security ApiKeyAuth

Сделать это или условие

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

Сделать это и состояние

 // @Security ApiKeyAuth && firebase
// @Security OAuth2Application[write, admin] && APIKeyAuth

Добавить описание для элементов перечисления

 type Example struct {
	// Sort order:
	// * asc - Ascending, from A to Z.
	// * desc - Descending, from Z to A.
	Order string `enums:"asc,desc"`
}

Генерировать только конкретные типы файлов DOCS

По умолчанию команда swag генерирует спецификацию Swagger в трех разных типах файлов/файлов:

Docs.go
Swagger.json
Swagger.yaml

Если вы хотите ограничить набор типов файлов, которые должны быть сгенерированы, вы можете использовать флаг --outputTypes (short -ot ). Значение по умолчанию - go,json,yaml - Типы выводов, разделенные с запятой. Чтобы ограничить вывод только для go и файлов yaml , вы бы пишете go,yaml . С полной командой, которая будет swag init --outputTypes go,yaml .

Как использовать дженерики

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

Смотрите этот файл для получения более подробной информации и других примеров.

Изменить делимиторы шаблона по умолчанию

#980 #1177

Если ваши аннотации Swagger или поля структуры содержат «{{" или "}}", генерация шаблонов, скорее всего, потерпит неудачу, так как это делимиторы по умолчанию для шаблонов GO.

Чтобы поколение работало должным образом, вы можете изменить делимиторы по умолчанию с помощью -td . Например:

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

Новый разделитель - это строка с форматом « <left delimiter> , <right delimiter> ».

Анализ внутренних пакетов и зависимостей

Если структура определен в пакете зависимостей, используйте --parseDependency .

Если структура определена в вашем основном проекте, используйте --parseInternal .

Если вы хотите включить как внутренние, так и от зависимостей, используйте оба флага

 swag init --parseDependency --parseInternal

О проекте

Этот проект был вдохновлен Ивасияровым/Swagger, но мы упростили использование и добавили поддержку различных веб -структур. Источником изображения суслика является Tenntennn/Gopher-Shickers. У него есть лицензии Creative Commons Licensing.

Участники

Этот проект существует благодаря всем людям, которые вносят свой вклад. [Способствовать].

Покровители

Спасибо всем нашим покровителям! [Станьте покровителем]

Спонсоры

Поддержите этот проект, став спонсором. Ваш логотип будет отображаться здесь со ссылкой на ваш сайт. [Станьте спонсором]

Лицензия

Расширять