Первоначально опубликовано вISALND

Нравится ли вам писать документацию?~~мне нравится~~.

Поэтому документация стала болью в сердцах разработчиков. особенно используяrestfulИнтерфейс стал обязательным для написания документов, иначе студенты не узнают, что вы написали. Так что дайте мне написать документацию, лучше меня убейте! ! !

Далее мы представим артефакт ---swagger

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

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

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

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

Сказал много вышеswaggerКак насчет, в конце концов, вам все равно придется писать это самому? На самом деле нет, пусть наш проект интегрируетсяswagger, интерфейсный документ проекта в дальнейшем может быть сгенерирован автоматически.

Первый для установкиswagger.

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

Дождаться окончания установки, выполнить в нашем терминалеswag init, каталог является корневым каталогом, вmain.goтот же каталог.

После завершения выполнения в корневом каталоге будет создан новыйdocsпапка.

docs
|
|-docs.go
|-swagger.json
|-swagger.yaml

Следующим шагом является завершение проекта.

Поместите следующие две строки вinitRouterсерединаimportсередина.

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

выберитеSync packages of GinHello,В настоящее времяIDEОн автоматически загрузится для меня и добавит его вgo.modсередина.

Если загрузка здесь не удалась, пожалуйста,go modДобавить прокси.

добавить прокси File-Setting-Go-Go Modules(vgo)-Proxy
Агент добавленmirrors.aliyun.com/goproxy/Это зеркало модов, созданное Али недавно. Конечно, вы также можете выбрать другие зеркальные агенты.

Дождитесь завершения загрузки пакета.

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

правильноswaggerПосле завершения установки мы можем интегрировать проект.

существуетinitRouterДобавьте маршрут, этот маршрут правильный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Добавьте комментарий к методу. В то же время представить наше поколениеdocs.go

package main

import (
	_ "GinHello/docs"
	"GinHello/initRouter"
)

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

// @contact.name youngxhu
// @contact.url https://youngxhui.top
// @contact.email youngxhui@g mail.com

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

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

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

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

в нашемhandlerдобавить заметку

ОткрытымarticleHandler.go,существуетInsertдобавлен метод.

// @Summary 提交新的文章内容
// @Id 1
// @Tags 文章
// @version 1.0
// @Accept application/x-json-stream
// @Param article body model.Article true "文章"
// @Success 200 object model.Result 成功后返回值
// @Failure 409 object model.Result 添加失败
// @Router /article [post]

@Summary — это описание интерфейса
@Id — это глобальный идентификатор, Id может быть отмечен не во всех интерфейсных документах.
@Tags — это аннотация интерфейса, этот же тег — это группа, чтобы мы могли организовать интерфейс
@Version указывает версию интерфейса
@Accept указывает тип запроса запроса
@Param указывает, что параметры имеют следующие параметры: имя параметра, тип параметра, тип данных, требуется ли комментарий, атрибут (необязательный параметр), а параметры разделены пробелами.
@Success указывает, что запрос возвращается после успешного запроса, имеет следующие параметры: код состояния возврата запроса, тип параметра, тип данных, комментарий.
@Failure Возвращает после сбоя запроса, параметры такие же, как указано выше.
@Router Эта функция определяет маршрут запроса и содержит метод запроса маршрута.

Можно просмотреть определенные типы параметров, типы данных и т. д.официальная документация

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

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

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

На этом комментарии к документации для добавления интерфейса завершены.

Мы используем общий метод для улучшения основыidДокументация по интерфейсу для запроса данных.

существуетGetOneДобавьте приведенный выше комментарий к методу.

// @Summary 通过文章 id 获取单个文章内容
// @version 1.0
// @Accept application/x-json-stream
// @Param id path int true "id"
// @Success 200 object model.Result 成功后返回值
// @Router /article/{id} [get]

мы похожи/article/:idинтерфейс, окончательный идентификатор передается через{}пакет.

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

package model

type Result struct {
	Code    int         `json:"code" example:"000"`
	Message string      `json:"message" example:"请求信息"`
	Data    interface{} `json:"data" `
}

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

Точно так же мы можемarticleкомментировать.

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

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

✍Резюме

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

👨‍💻 Код для этой главы

Github

Личный публичный аккаунт

Официальный аккаунт в настоящее время одновременно обновляет серию статей Gin, и вы можете обратить внимание на:Охотник за кодом