Gin + Swagger для быстрого создания документации по API

Go API
Gin + Swagger для быстрого создания документации по API

задний фон

При соединении front-end и back-end проектов restful необходимо иметь четкий интерфейсный документ, в это время написание интерфейсного документа только для интерфейса занимает много времени и сил. изменен, интерфейсный документ необходимо поддерживать. В настоящее время легко иметь несогласованные документы. Это лучший способ написать интерфейсную документацию непосредственно в коде.

Swagger решает эту проблему: разработчикам нужно только писать комментарии swagger при написании кода интерфейса в соответствии с конкретными спецификациями и использовать swagger для создания документов интерфейса.

2 Введение в пользовательский интерфейс Swagger

SwaggerЯвляетсяAPIСоздание инструментов, которые могут генерировать документацию.Swaggerнаписаноyamlа такжеjsonдля достижения документации. И может сделать тестирование и так далее.

пройти черезswaggerИнтерфейсные документы легко генерируются, что удобно для внешнего просмотра и тестирования.

Интеграция трех проектов

3.1 Установить хабар

$ go get github.com/swaggo/swag/cmd/swag

3.2 Создание файлов

Связанные файлы создаются впервые, а код был изменен позже.После добавления аннотации swag также необходимо

# 在go 项目中（包含main.go）的目录，使用swag init命令生成相关文件。
$ swag init
2021/09/23 16:32:23 Generate swagger docs....
2021/09/23 16:32:23 Generate general API Info, search dir:./
2021/09/23 16:32:26 create docs.go at docs/docs.go
2021/09/23 16:32:26 create swagger.json at docs/swagger.json
2021/09/23 16:32:26 create swagger.yaml at docs/swagger.yaml

3.3 Установить джин-чванство

$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/gin-swagger/swaggerFiles

3.4 Интеграция

  • Импортируйте сгенерированный пакет документов
  • Согласно спецификации на конкретный интерфейсswagНапишите описание интерфейса
  • Импорт в маршрутизацию
  • Выполните swag init еще раз, чтобы обновить интерфейс.
  • После запуска приложения браузер получает доступ:http://localhost:8887/swagger/index.html 
package main

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

	_ "github.com/swaggo/gin-swagger/example/basic/docs" // docs is generated by Swag CLI, you have to import it.
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore 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 petstore.swagger.io
// @BasePath /v2
func main() {
	r := gin.New()

	url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

	r.Run()
}

Четыре разных типа

4.1 Запрос

4.1.1 параметры URL

// @Param id path int true "ID"    //url参数：（name；参数类型[query(?id=),path(/123)]；数据类型；required；参数描述）

4.1.2 параметр тела

например json

// @Param data body models.RegistryAuth true "请示参数data"

4.2 Возврат

4.2.1 Строки

// @Success 200 {string} json "{"msg":"ok"}"

4.2.2 Возврат структуры

// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"

Пять настоящих боев

5.1 основная функция добавляет глобальную

// @title smartkm_api_image Swagger Example
// @version 1.0
// @description This is a sample server Petstore 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 petstore.swagger.io
// @BasePath /
func main() {
	// 启动服务
	run()
}

5.2 Функциональный уровень

5.2.1 Получить запрос

// @Summary 查看迁移任务详细信息
// @Description 查看迁移任务详细信息
// @Accept json
// @Produce  json
// @Param task_id path string true "task_id"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [get]

5.2.2 Отправка запроса

// @Summary 创建镜像迁移任务
// @Description 创建镜像迁移任务
// @Accept  json
// @Produce  json
// @Param data body models.CreateTaskReq true "请示参数data"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [post]

5.2.3 Удалить запрос

// @Summary 删除镜像迁移任务
// @Description 删除镜像迁移任务
// @Accept  json
// @Produce  json
// @Param data body models.TaskReq true "请示参数data"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [delete]

Меры предосторожности

  • При добавлении swagger в маршрут вам необходимо импортировать пакет документов, созданный проектом.
  • Если аннотация swagger, отмеченная в заголовке метода func, неверна, при выполнении swag init будет сообщено об ошибке, и она будет изменена в соответствии с информацией об ошибке;
  • Доступ к консоли swagger сообщает об ошибке 404, страница не найдена, поскольку маршрут swagger не добавлен
  • Доступ к консоли swagger и сообщение об ошибке Не удалось загрузить спецификацию из-за отсутствия импорта для представления папки документов swagger, сгенерированной swag init;

Ссылка на ссылку

Категории