Использование swagger для создания проектных документов с высокой доступностью — статьи GO

Go

Вы тоже не проецируете документальные пытки? Вам нужно написать проект документа из-за головной боли? Вы тоже попали в ловушку с ветхими документами? Мальчик, съев мой Amway сделал это! Развернув Swagger, эти проблемы будут далеко от вас, красивые, читаемые, тестируемые, срочные документы, вы не хотите попробовать?

введение

Основная концепция swagger и основная идея построения всего проекта, а также предыдущие статьи,Использование swagger для создания проектной документации с высокой доступностью — статьи о PHPЗдесь это не повторяется, здесь описываются только различия между развертыванием и использованием.

развертывать

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

  • Установите базовые компоненты сначала

      go get -u github.com/go-swagger/go-swagger/cmd/swagger

    Рекомендуется использовать go get для прямой установки. Многие проекты, установленные с помощью brew, столкнутся с проблемой неправильного чтения пути GOROOT. Если вы столкнетесь с подобными проблемами, вы можете обратиться к следующей проблеме.

    issue

  • добавить комментарии к интерфейсу

    Синтаксис комментария может относиться кПравила использования официальных документов

      这里提供一组简单的例子，笔者使用的是go+kit，未使用框架
  
  由于go kit提供了endpoint层，request和response由服务框架自动生成，可以方便的在上面添加注释
  
  // Package classification Example api.
  //
  // This is an example api
  //
  //      Host: 127.0.0.1
  //      Version: 1.0.0
  //
  // swagger:meta
  
  package endpoint
  
  // swagger:parameters GetExampleRequest
  type GetExampleRequest struct {
  // in: query
  Id    string `json:"id"`
  }
  
  // example api response
  // swagger:response GetExampleResponse
  type GetExampleResponse struct {
      // response body
      // in: body
      Body struct {
          // the code og response
          //
          // Required: true
          Code    int             `json:"code"`
          // the message of response
          //
          // Required: true
          Message string          `json:"message"`
          // response data
          Data    interface{}     `json:"data"`
      }
  }
  
  // swagger:route GET /example tag GetExampleRequest
  //
  // example route
  //
  // This is an example route
  //
  // Responses:
  // 200: GetExampleResponse

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

  • Получить стандартный Swagger Json

    Нужно только выполнить в корневом каталоге проекта

      swagger generate spec -o ./swagger.json

    Эта команда начнет сканирование с файла main.go проекта и проанализирует все комментарии чванства. На этом этапе файл swagger.json будет сгенерирован в корневом пути проекта.Принимая приведенные выше комментарии в качестве примера, сгенерированный контент выглядит следующим образом

      {
      "swagger": "2.0",
      "info": {
          "description": "This is an example api",
          "title": "Example api.",
          "version": "1.0.0"
      },
      "host": "127.0.0.1",
      "paths": {
          "/example": {
              "get": {
                  "description": "This is an example route",
                  "tags": [
                      "tag"
                  ],
                  "summary": "example route",
                  "operationId": "GetExampleRequest",
                  "parameters": [
                      {
                          "type": "string",
                          "x-go-name": "Id",
                          "name": "id",
                          "in": "query"
                      }
                  ],
                  "responses": {
                      "200": {
                          "$ref": "#/responses/GetExampleResponse"
                      }
                  }
              }
          }
      },
      "responses": {
          "GetExampleResponse": {
              "description": "example api response",
              "schema": {
                  "type": "object",
                  "required": [
                      "code",
                      "message"
                  ],
                  "properties": {
                      "code": {
                          "description": "the code og response",
                          "type": "integer",
                          "format": "int64",
                          "x-go-name": "Code"
                      },
                      "data": {
                          "description": "response data",
                          "type": "object",
                          "x-go-name": "Data"
                      },
                      "message": {
                          "description": "the message of response",
                          "type": "string",
                          "x-go-name": "Message"
                      }
                  }
              }
          }
      }
  }

    На этом этапе родились стандартные данные Swagger Json. Следующая идея очень проста, написать новый интерфейс, вывести файл json напрямую, а затем использовать предыдущую статьюИспользование swagger для создания проектной документации с высокой доступностью — статьи о PHPПлагин Chrome, упомянутый в, может напрямую открывать интерфейс.

На этом этапе родился быстрый и удобный документ go swagger Конкретный способ его использования зависит от личных предпочтений каждого.Hope you enjoy it!

Справочные документы

Go Swagger

Официальная документация Go Swagger

официальный сайт Swagger

Объяснение стандартного параметра Swagger

Swagger Спецификация OpenAPI

Категории