Как серверная часть на работе предоставляет API? свагго это хорошо

задняя часть
Как серверная часть на работе предоставляет API? свагго это хорошо

Это первый раз, когда я участвую в Gengwen Challenge.26День, подробности о событии уточняйте:Обновить вызов

Как серверная часть на работе предоставляет API? свагго это хорошо

В прошлый раз, когда мы кратко поделились Casbin управления разрешениями GO, он обычно ссылается наВ соответствии с правилами безопасности или политиками безопасности, установленными системой

  • поделился, что такое управление разрешениями
  • что такое кабин
  • Особенности Касбина
  • Кейсы для Casbin

Если вы заинтересованы, мы можем обсудить и поделиться более подробно в будущем, добро пожаловать в статьюCasbin для управления разрешениями GO

Сегодня давайте расскажем, как работают наши серверные партнеры.APIЭффективно предоставлять?

API состоит из набора определений и протоколов, которые можно использовать для создания и корпоративной интеграции прикладного программного обеспечения.

API естьинтерфейс прикладного программирования

Я считаю, что многие друзья, которые любят писать документы, могут использоватьmarkdownЗапишите интерфейс, и соответствующее ответственное лицо согласует фиксированный шаблон

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

А при тестировании?

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

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

Тогда давайте посмотрим на GOswaggoКак инструмент решает вышеперечисленные проблемы и какие есть хитрости?

Что такое свагго?

это инструмент, предназначенный дляgolangАннотации автоматически преобразуются вSwagger 2.0Документация

Что такое Сваггер?

Swaggerэто веб-сервис

Это каноническая и полная структура для создания, описания, вызова и визуализации документов в стиле RESTful.

Так в чем же его преимущество?

примерно так2Преимущества:

  • Поддержка API для автоматического создания синхронизированной онлайн-документации

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

  • Предоставляет API для онлайн-тестирования веб-страниц.

SwaggerСгенерированная документация также поддерживает онлайн-тестирование

Все параметры и форматы установлены, и вы можете напрямую вводить значения, соответствующие параметрам интерфейса, для тестирования интерфейса в режиме онлайн.

Как мы используем свагго?

Давайте напишем базовый для васswaggoИспользование кейса условно делится на следующие этапы:

  • Установитьswag, для автоматического документирования
  go get -u github.com/swaggo/swag/cmd/swag
  • Вам нужно использовать следующие 2 пакета. Сначала вы можете узнать. Мы по-прежнему используем go mod по умолчанию. После написания кода перейдите к сборке напрямую, и все используемые пакеты будут извлечены.

первыйgin-swagger, нам удобнее использовать джин для игры в чванство, и я делился им с вами ранееginЕсли вы заинтересованы, вы можете проверить статьюДжин боевая тренировка

go get github.com/swaggo/gin-swagger

Второйswaggerвстроенный файл

go get github.com/swaggo/gin-swagger/swaggerFiles
  • Требуется простое использование фреймворка gin

Давайте начнем кодировать простой маленькийDEMO

package main

import (
   "github.com/gin-gonic/gin"
   ginSwagger "github.com/swaggo/gin-swagger"
   "github.com/swaggo/gin-swagger/swaggerFiles"
   "net/http"
   _ "myswa/docs"
)

// gin 的处理函数  Hello
func Hello(c *gin.Context) {

   c.JSON(http.StatusOK, gin.H{"msg": "hello wrold xiaomotong" })
}

func main() {

   r := gin.Default()

   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

   // 路由分组， 第一个版本的api  v1
   v1 := r.Group("/api/v1")
   {
      v1.GET("/hello", Hello)

   }

   // 监听端口为 8888
   r.Run(":8888")
}

Приведенный выше код примерно разделен на следующие шаги:

  • использоватьr.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))Зарегистрируйте swaggerFiles.Handler на
  • Напишите собственный маршрут и соответствующий метод
  • Прослушать указанный адрес и порт

После того, как приведенный выше код написан, мы можемmain.goИнициализируйте один в родственном каталогеgo модуль, затемgo buildмы запускаем программу

go mod init myswa
go build

указанная выше командаgo mod init myswa, модуль инициализацииmyswa, после импорта нашего локального пути к пакету он должен бытьmyswaначало

После выполнения вышеуказанной командыmyswa модуль, который выполняет go buildПосле этого соответствующие используемые пакеты будут извлечены и скомпилированы.

После успешной компиляции введите в браузере:

http://127.0.0.1:8888/swagger/index.html

Если вы видите следующее сообщение об ошибке, причина в том, что он не установленswagизdocs

Здесь вы можете проверить, успешно ли установлен swag

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

После успешной установки вы можете использовать swag init для инициализации,swagпоможет нам создать соответствующийdocs, например мой каталог кода выглядит так

Вот почему один из импортированных нами пакетов_ "myswa/docs"

Введите в браузере еще раз:

http://127.0.0.1:8888/swagger/index.html, вы можете увидеть следующий эффект, это успешно

добавить заметки

мыmain.goВ файл добавьте несколько комментариев, чтобы увидеть эффект, например

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"net/http"
	_ "myswa/docs"
)

// gin 的处理函数  Hello
func Hello(c *gin.Context) {

	c.JSON(http.StatusOK, gin.H{"msg": "hello wrold xiaomotong" })
}
// @title Xiaomotong Swagger  API
// @version 1.0
// @description 参加更文挑战第 26 天了，主题是 Swagger
// @termsOfService https://juejin.cn/user/3465271329953806

// @contact.name https://juejin.cn/user/3465271329953806
// @contact.url https://juejin.cn/user/3465271329953806
// @contact.email xxx@xxx.com.cn


// @host 127.0.0.1:8888
// @BasePath /api/v1
func main() {

	r := gin.Default()

	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	// 路由分组， 第一个版本的api  v1
	v1 := r.Group("/api/v1")
	{
		v1.GET("/hello", Hello)

	}

	// 监听端口为 8888
	r.Run(":8888")
}

После добавления комментария выполните следующее3шаг:

  • Удалить созданный ранее каталог документов
  • снова вmain.goВыполнить в том же каталогеswag initСоздание последней документации
  • воплощать в жизньgo run main.go, доступ через браузерhttp://127.0.0.1:8888/swagger/index.htmlМы можем наблюдать следующий эффект

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

Они автоматически генерируются

my_swa/docs/swagger.jsonследующим образом

{
    "swagger": "2.0",
    "info": {
        "description": "参加更文挑战第 26 天了，主题是 Swagger",
        "title": "Xiaomotong Swagger  API",
        "termsOfService": "https://juejin.cn/user/3465271329953806",
        "contact": {
            "name": "https://juejin.cn/user/3465271329953806",
            "url": "https://juejin.cn/user/3465271329953806",
            "email": "xxx@xxx.com.cn"
        },
        "version": "1.0"
    },
    "host": "127.0.0.1:8888",
    "basePath": "/api/v1",
    "paths": {}
}

my_swa/docs/swagger.yamlследующим образом:

basePath: /api/v1
host: 127.0.0.1:8888
info:
  contact:
    email: xxx@xxx.com.cn
    name: https://juejin.cn/user/3465271329953806
    url: https://juejin.cn/user/3465271329953806
  description: 参加更文挑战第 26 天了，主题是 Swagger
  termsOfService: https://juejin.cn/user/3465271329953806
  title: Xiaomotong Swagger  API
  version: "1.0"
paths: {}
swagger: "2.0"

действительныйUIПоказанные данные взяты из двух вышеуказанных файлов.

Для ключевых слов в комментариях выше, давайте сделаем таблицу, чтобы увидеть

tag иллюстрировать
titile название документа
version Версия
description Описание, доступное для записи или нет
host портовый документ
BasePath базовый путь
Summary Суммировать
Description описывать
Tags Используется для группировки API
Accept Тип принимаемого параметра, поддерживает форму (mpfd) и JSON(json)
Param Параметры, конкретная запись выглядит следующим образом:
@Param 参数名 参数类型 参数数据类型 是否必须 参数描述 其他属性
тип параметра
- pathЗначения этого типа могут быть напрямую вставлены в URL
@Param name path string true "конкретное имя"-queryЭтот тип значения обычно сочетается с URL

- queryЭтот тип значения обычно сочетается с URL
Строка запроса имени @Param true "конкретное имя"

- formDataЗначения этого типа обычно используются для метода POST или метода PUT.
@Param name formData string true "конкретное имя" по умолчанию (корень)

Типы данных параметров следующие**
строка(строка) , целое число (int, uint, uint32, uint64) , число (float32) , логическое значение (bool) , файл для загрузки файлов

Дополнительная поддержка недвижимости:
- 枚举
- 值的添加范围
- 设置默认值
Success Как быть с успешным ответом
@Success HTTP响应码 {响应参数类型} 响应数据类型 其他描述
Failure Что делать, если ответ не работает
@FailureHTTP响应码 {响应参数类型} 响应数据类型 其他描述
Router маршрутизация, без базового пути
@Router /hello [get]

Добавим к функции соответствующие комментарии, чтобы увидеть эффект

// @Summary hello world
// @Description 对谁说 hello wrold
// @Tags 挑战测试
// @Accept json
// @Param name query string true "具体名字"
// @Success 200 {string} string "{"msg": "hello xxx"}"
// @Failure 400 {string} string "{"msg": "NO name"}"
// @Router /hello [get]
// gin 的处理函数  Hello
func Hello(c *gin.Context) {
   name := c.Query("name")
   c.JSON(http.StatusOK, gin.H{"msg": "hello wrold" + name})
}

После добавления комментария выполните следующее3шаг:

  • Удалить созданный ранее каталог документов
  • снова вmain.goВыполнить в том же каталогеswag initСоздание последней документации
  • воплощать в жизньgo run main.go, доступ через браузерhttp://127.0.0.1:8888/swagger/index.htmlМы можем наблюдать следующий эффект

Проведем базовый тест на странице, заполним имя, выполним и посмотрим на эффект

Нет, тест прошел успешно

Если такой документ дадут, то он будет очень дружелюбен к интерфейсу, и это не увеличит нашу нагрузку.При написании кода, кстати, пишите комментарии.

выпускать

После завершения разработки, когда версия выпущена, невозможно внести своюapiЗадокументируйте это, этого не должно быть

Следовательно, мы можем пройтиbuild tagспособ контролировать, компилировать ли документ, вот ожидание, заинтересованные друзья могут попробовать

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

Суммировать

  • что такое свагго
  • что такое чванство
  • Как использовать свагго
  • Как протестировать свагго

Добро пожаловать лайк, подписка, избранное

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

Хорошо, вот и на этот раз,Таймер Next GO и временная задача cron

Технологии открыты, и наш менталитет должен быть открытым. Примите перемены, живите на солнце и двигайтесь вперед.

ямаленький дьяволенок Нежа, добро пожаловать, лайкайте, подписывайтесь и добавляйте в избранное, увидимся в следующий раз~

Категории