Do you suffer from projects that have no documentation? Are you struggling to document your projects? Have you been victimized by disrepair documents? Boy, eat my amway! By deploying Swagger, these problems will be removed from your elegant, readable, testable, time-sensitive document. Don’t you want to try?

The introduction

The basic concept of Swagger and my basic idea of building the whole project are the same as those mentioned in the previous article, using Swagger to build a high-availability project document — PHP. I will not repeat the above, but only describe the differences in the deployment and use process.

The deployment of

Please refer to the official documentation for the go infrastructure installation, which assumes that you already have a stable go environment.

  • Start by installing the base components

      go get -u github.com/go-swagger/go-swagger/cmd/swagger
Copy the code

    It is recommended to install using Go Get directly. Many projects installed using BREW will encounter problems that GOROOT paths cannot be read correctly. If you encounter similar problems, please refer to the following issue

    issue

  • Add comments to the interface

    You can refer to the official documentation for comment syntax

    Here is a set of simple examples. The author uses Go + Kit, but does not use the framework. Since go Kit provides the endpoint layer, request and response are automatically generated by the service framework. // // This is an Example API // // Host: 127.0.0.1 // Version: 1.0.0 // // swagger: Meta Package endpoint // Swagger :parameters GetExampleRequest type GetExampleRequest struct {  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: GetExampleResponseCopy the code

    Copying the example gives you an interface with standardized annotations

  • Get standard Swagger Json

    You only need to execute in the project root directory

      swagger generate spec -o ./swagger.json
Copy the code

    This command will scan from the main.go file of the project and parse all swagger comments. At this point, a Swagger

    {"swagger": "2.0", "info": {"description": "This is an example API ", "title": "example API.", "version": "1.0.0"}, "the 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" } } } } } }Copy the code

    At this point, a standard Swagger Json data is born. Json file, and then use swagger to create a high availability project document.

Here’s a quick and convenient Go Swagger document. It’s up to you to use it. Hope you enjoy it!

Reference documents

Go Swagger

Go Swagger official Usage documentation

Swagger website

Swagger standard parameter description

Swagger OpenAPI specification