gin-swagger генерирует документацию OpenAPI в стиле RESTful

Swagger

📜 Что такое чванство

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

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


🔧 Установить чванство

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

Перед установкой рекомендуется открыть go mod и использовать goproxy для скачивания

Сначала вам нужно установить swagger

go get -u github.com/swaggo/swag/cmd/swag

Убедитесь, что установка прошла успешно

$ swag -v
swag version v1.6.7

🍔 Интеграция чванства

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

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

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

настройка маршрутизации джина

существует

router
Добавьте маршрут, этот маршрут правильныйswaggerадрес доступа для добавления

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

вurlОпределенныйswaggerизdoc.jsonпуть, мы можем напрямую получить доступ кjsonсмотреть.

Конфигурация документа

Следующим шагом является улучшение документации:

существуетmain.goсерединаmainДобавьте комментарий к методу.

package main

import (
	_ "GinHello/docs" //此处导入的是swag init 生成docs文件所在路径
	"GinHello/initRouter" //导入路由
)

// @title Gin swagger
// @version 1.0
// @description Gin swagger 示例项目

// @contact.name ganlei
// @contact.url https://juejin.cn/user/1943592291283309
// @contact.email ganlei@uniontech.com

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

// @host localhost:9090
func main() {
    // 省略其他代码
}

Приведенные выше комментарии в основном хорошо понятны и не слишком много объясняют.

Это основные вводные аннотации проекта, а затем аннотации методов нашего интерфейса.

в нашемhandlerдобавить примечание

SwaggerВам необходимо написать соответствующие комментарии или аннотации к методу, а затем использовать генератор для автоматической генерации файла описания.

gin-swaggerДан пример:

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

мы можем обратиться кSwaggerСпецификации аннотаций и примеры для написания

Ссылочные примечания см.официальная документация.чтобы убедиться, что вы получаете последний синтаксис swag


Места, которые не описаны в документе, объясняются здесь, оParamТипы параметров следующие

  • запрос похож\user?username=Jack&age=18
  • тело должно поместить данные в тело для запроса
  • путь похож\user\1

Разные типы параметров соответствуют разным запросам, пожалуйста, используйте их соответствующим образом.

Мы передаем параметры в путь следующим образом/user/:nameИнтерфейс , конечное имя передается через{}пакет.

как правило@Успех,@FailureВозвращенный результат может быть упакован в модель структуры. Результат

package model

type Result struct {
        Result bool         `json:"result" example:"请求结果true或者false"`
	Code    int         `json:"code" example:"000"`
	Data    interface{} `json:"data" `
}

мы правыResultсерединаtagтам будетexample, это ещеswaggerтег, чтобы дать структуре пример.

Генерировать файлы, соответствующие чванству

Когда мы закончим со всеми комментариями кода, повторно выполните в консолиswag init, который будет создан на основе наших аннотацийdocs.goи соответствующие файлы json и yaml.

Примечаниеswag init Необходимы инструкции в проектеКорневая директорияВыполните ниже, чтобы swag мог сканировать аннотации swagger во всем проекте.

По команде:

swag init -h 

Вы можете проверить соответствующую справку, если функция main.go не находится в корневом каталоге проекта, вы можете использовать следующую команду:

swag init -g ./../main.go - o ./docs

Здесь используется относительный путь относительно расположения корневого каталога вашего проекта main.go.

Дополнительные инструкции

Комментарий выше main в файле main.go имеет @BasePath, обычно при использовании разрешения доменного имени доступ к API-интерфейсу осуществляется в этой форме /api/v1

Если вы столкнулись с междоменными проблемами, вы можетеRouterплюс функция обработчика

//Cors ...允许跨域设置func Cors() gin.HandlerFunc {    return func(c *gin.Context) {        c.Header("Access-Control-Allow-Origin", "*")        c.Header("Access-Control-Allow-Credentials", "false")        c.Next()    }}

проверять

Чтобы начать наш проект, посетитеhppt://localhost:9090/swagger/index.htmlВы можете просмотреть нашу документацию, эффект выглядит следующим образом




✍Резюме

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


Категории