Super efficient! The secret of swagger Yapi

Reading guide

： Believe in both front-end and back-end development , Are more or less tortured by interface documents . The front end often complains that the interface document given by the back end is inconsistent with the actual situation . The back end also thinks that writing and maintaining interface documents will cost a lot of energy , Often too late to update . In fact, whether the front end calls the back end , Back end calls back end , All expect a good interface document . But over time , Version of the iteration , Interface documents are easy to lose track of code , There will also be former students who leave without clearly handing over the interface documents , Leave a heavy and complex project , It's very difficult to chew it again , No less than writing it all over again . Therefore, it is not enough to regulate everyone only through coercion . We studied Swagger To Yapi How to get through . With it , We can write code every time , Just modify the comments by the way , And then submit ,Yapi Our interface documents can be automatically changed on .

The full text 8199 word , Estimated reading time 21 minute .

One 、Swagger brief introduction

Swagger Is a specification and complete framework , Used to generate 、 describe 、 Invocation and visualization RESTful style Web service . You just need to define the interface and the interface related information according to its specifications . Re pass Swagger A series of derived projects and tools , You can generate various formats of interface documents , Generate multi language client and server code , And online interface debugging page and so on .

such , If you follow the new development model , When developing new or iterative versions , Just update Swagger Description file , Can automatically generate interface documents and client server code , Call end code 、 Consistency of server code and interface documents .

Two 、Swagger build

The following steps are based on the successful operation of go On the environment .

stay go-swagger The most complete tutorial can be seen on the official tutorial , Those who have the ability can go directly to the official tutorial .

2.1

► install

All the above download methods are feasible , But in order to be compatible with all our situations , So choose this , Download the code directly .

Simplify the order , Actually, I did two things ：

1、clone go-swagger Code for ;

2、 hold swaager add GOROOT.

mkdir DownLoad
cd DownLoad
git clone https://github.com/go-swagger/go-swagger
cd DownLoad/go-swagger-master/cmd/swagger/
go install .


To see if it works ：

[[email protected] /]$ swagger -h
Usage:
 swagger [OPTIONS] <command>

Swagger tries to support you as best as possible when building APIs.

It aims to represent the contract of your API with a language agnostic description of your application in json or yaml.


Application Options:
 -q, --quiet silence logs
 --log-output=LOG-FILE redirect logs to file

Help Options:
 -h, --help Show this help message

Available commands:
 diff diff swagger documents
 expand expand $ref fields in a swagger spec
 flatten flattens a swagger document
 generate generate go code
 init initialize a spec document
 mixin merge swagger documents
 serve serve spec and docs
 validate validate the swagger document
 version print the version


2.2

► build

• This part is all about swagger Usage of , Let's start with the simplest , Interface notes , Copy the comments above the sample to the top of the interface ：

• Sample document comments ：

• function swagger, Generate interface document

• command ：swagger generate spec -o ./swagger.json

• start-up swagger service , Enter the interface document page

• command ：swagger serve --no-open swagger.json

3、 ... and 、Swagger standard

Swagger The specification and usage of notes are as follows .

3.1

►swagger:meta

brief introduction ：swagger:meta  It's all you have API Summary , We use it to form our API Introduction at the beginning of the document .

// Go-Swagger API.(title)
//
//  This is our test API (description)
//
// Terms Of Service:
// there are no TOS at this moment, use at your own risk we take no responsibility
//
// Schemes: http, https
// Host: localhost
// BasePath: /go-swagger/test
// Version: 0.0.1
// License: MIT http://opensource.org/licenses/MIT
// Contact: Zhubangzheng<[email protected]> [email protected]
//
// Consumes:
// - application/json
// - application/xml
//
// Produces:
// - application/json
// - application/xml
//
// Security:
// - api_key:
//
// SecurityDefinitions:
// api_key:
// type: apiKey
// name: KEY
// in: header
// oauth2:
// type: oauth2
// authorizationUrl: /oauth2/auth
// tokenUrl: /oauth2/token
// in: header
// scopes:
// bar: foo
// flow: accessCode
//
// Extensions:
// x-meta-value: value
// x-meta-array:
// - value1
// - value2
// x-meta-array-obj:
// - name: obj
// value: field
//
// swagger:meta
package test


Be careful ： The end of the comment  swagger:meta and package There can be no blank line , Otherwise, it cannot be swagger distinguish .

Note usage ：

3.2

►swagger:route

swagger:route  Is the main annotation parameter , It's your single API Interface details .

Format

：swagger:route [method] [path pattern] [tag1 tag2 tag3] [operation id]

[method] and  [path pattern] Mandatory , hinder [tag] It's up to you , The first is your current interface tag, Then consider adding others . final [operation id] Is the only identification of your method , If it is only used as an interface document, you can leave it blank , But it is used as a method name in many places . For example, methods for client generation .

 // ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
 // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
 //
 // Swagger Test interface
 //
 //  be used for Swagger test
 //
 // Consumes:
 // - application/json
 // - application/x-protobuf
 //
 // Produces:
 // - application/json
 // - application/x-protobuf
 //
 // Schemes: http, https, ws, wss
 //
 // Deprecated: true
 //
 // Security:
 // api_key:
 // oauth: read, write
 //
 // Responses:
 // default: genericError
 // 200: someResponse
 // 422: validationError
 mountItem("GET", basePath+"/{id}/checkout", nil)
}


Response And defined later swagger:response Corresponding .

3.3

►swagger:patameters

swagger:parameters  It is the Parameter annotation of the interface

Format

：swagger:parameters [operationid1 operationid2],parameters  adopt [operation id] and route binding .

There are many ways to play parameters , But it's basically useless. You can check it in the official documents swagger:parameters.

Because we mainly use GET、POST, The official website only introduces GET Method , Intranet and extranet for swagger:parameters Annotated POST There is little introduction to the usage of , So here we introduce GET and POST The main way to play .

// swagger:parameters swagger_test_checkout 
type SwaggerTest struct {
 // SwaggerTest Interface test parameters 1 (description)
 // required: true( Whether must )
 // in: query( Where the parameter is located )
 ID uinat64 `json:"id"`
}


a key ：GET Methodical  in  notes   Connectable  query、header、cookie、path , It depends on different situations .

The above is our statement GET Necessary comments for the parameters of , Everything else is unnecessary , Here's the picture , You can add .

• POST:

// swagger:parameters swagger_test_checkout 
type SwaggerTest struct {
 // SwaggerTest Interface test parameters 1 (description)
 // required: true( Whether must )
 // in: formData( Where the parameter is located )
 ID uinat64 `json:"id"`
}


POST Method , The position of the parameter is not body, In other words, No  in:body, But to use  in:formData, This format is imported into yapi Then it will appear in body in , And in the local swagger ui In order to display correctly . Another thing to note is that it is recommended to swagger:route Situated Consumes Set to  multipart/form-data, namely ：

 // ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
 // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
 //
 // Swagger Test interface
 //
 //  be used for Swagger test
 //
 // Consumes:
 // multipart/form-data
 //
 // ......
 mountItem("GET", basePath+"/{id}/checkout", nil)
}


Format

：swagger:response [response name] ,response  adopt [response name] and route As defined in response binding .

The usage of response comments and parameters is basically the same swagger:response, There is no need to repeat here , Direct example .

// A ValidationError is an error that is used when the required input fails validation.
// swagger:response validationError
type ValidationError struct {
 // The error message
 // in: body
 Body struct {
 // The validation message
 //
 // Required: true
 // Example: Expected type int
 Message string
 // An optional field name to which this validation applies
 FieldName string
 }
}


a key ： The above usage is response Basic usage , But in fact, it does not conform to the definition of the internal structure of many companies , So the following will talk about the real flexible and practical usage .

1、swagger:response  It can appear on any structure .

  There is no need to find our response layer , Or not even response Layer of , Instead, each interface defines a special response, Finally, use it uniformly interface Handle , This leads us to add swagger Extremely difficult .

for example ：

// SwaggerTestResponse
// swagger:response test_res
type SwaggerTestResponse struct {
 // The error message
 // in: body
 Body struct {
 // The validation message
 //
 // Required: true
 // Example: Expected type int
 Message string
 // An optional field name to which this validation applies
 FieldName string
 }
}


Be careful ：

： Must strictly follow the format ,Response A... Is nested under the structure Body Structure , That is to say, if it is our historical project , You have to Response Wrap another layer . for example ： This is a project that is being used Response return , We add swagger:response, The only one following it id,test, Use at the return of the interface .

// Test
// swagger:response old_api_resp
type OldAPIRes struct {
 // Test
 // in: body
 ID uint64
 Name string
 Time string
}

 // ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
 // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
 //
 // Swagger Test interface
 //
 //  be used for Swagger test
 //
 // Consumes:
 // - multipart/form-data
 // Schemes: http
 // Responses:
 // 200: old_api_resp
 mountItem("GET", basePath+"/{id}/checkout", nil)
}


And then we generate swagger.json, It is found that all parameters are defined in header Next , These return parameters should actually be located in body in , Otherwise, it cannot be swagger ui and yapi distinguish .

let me put it another way  swagger Of

in:body

Only recognize the nested structures in the structure , In order to cater to swagger Identification requirements , We transform the structure , Change to the following way , Can be identified in body In the .

// Test
// swagger:response old_api_resp
type OldAPIRes struct {
 // Test
 // in: body
 Body struct {
 ID uint64
 Name string
 Time string
 }
}


The above way of writing is actually very inconvenient , All interfaces Response Add one more layer below Body, This is not reasonable ,Swagger Just notes , Should not intrude code , Unless the original structure is like this , Otherwise, the above format is not recommended .

2、 premium swagger:model：

  Solved the above pain points , Truly flexible and easy to use .

swagger:model It's actually a swagger standard , The usage is very flexible , Detailed usage will be introduced later , Here we propose to use model solve response Methods .

Response Modification of comments ：

// swagger:model old_api_resp
type OldAPIRes struct {
 ID uint64
 Name string
 Time string
}


Route Note modification ：

// ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
 // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
 //
 // Swagger Test interface
 //
 //  be used for Swagger test
 //
 // Consumes:
 // - multipart/form-data
 // Produces:
 // - application/json
 // Schemes: http
 // Responses:
 // 200: body:old_api_resp
 mountItem("GET", basePath+"/{id}/checkout", nil)


Command to change ,-m It's a scan model:

swagger generate spec -m -o ./swagger.json 


To regenerate the , And then it's done .

Four 、Swagger-Yapi

Yapi An efficient 、 Easy to use 、 Powerful API Management platform .

Why should I get through Swagger To Yapi Well ？ The reason is simple .Swagger Of SwaggerUI Far from it Yapi Comprehensive function , and Yapi Can support importing Swagger.json Format interface document ,Swagger Convenience and Yapi The comprehensiveness of , We combine the two , So as to achieve better results .

4.1

►Nginx build

After the above steps, we should have generated our interface locally Swagger.json, and Yapi Manual import and automatic import are supported .

Manual import ：

Automatic import ：

What we need ？ What we need is every time Swagger After the update ,Yapi Will automatically update our interface , Then we naturally need to use Yapi Automatic import of , So we only need to build one on our own machine Nginx To do static file proxy , Can achieve .

Download and install nginx：

sudo yum install nginx -y


Check... After installation ：

rpm -qa | grep nginx


start-up nginx

sudo systemctl start nginx


or

sudo service nginx start


see nginx state

sudo systemctl status nginx


or

sudo service nginx status


4.2

► Proxy file

Get into nginx Catalog

cd /etc/nginx/


stay conf.d Add a new port to the directory that requires proxy

data The mapped directory depends on your actual situation , namely swagger.json Depending on the location of the directory .

cd conf.d/
vim yapi.conf

server {
 listen 8888;
 server_name localhost;

 location /data/ {
 alias '/home/work/Swagger/swagger-yapi/swagger-json/';
 }
}


restart nginx

sudo systemctl restart nginx


or

sudo service nginx restart


4.3

►Yapi Automatic synchronization

ip Corresponding to your own machine ip.

ip The address can be viewed through the following command ：

hostname -i


If prompted ：

Explain that the path is not right , You can enter the address into the browser to access , Adjust yourself to the right .

5、 ... and 、 Conclusion

Swagger There are many other uses , Light is through swagger -h Commands can see many uses , And its annotation usage also has many , There are also different ways of writing for different languages . Empathy ,Yapi As a powerful API The management platform is the same. It has many uses , Like online mock Interface, etc. . This article is just a quick start swagger To yapi Methods , After the passage is built , You can find more usage by yourself .

————————END————————

Recommended reading ：

Baidu live iOS SDK Platformized output transformation

Baidu APP  be based on Pipeline as Code Continuous integration practice of

Go  Language use  MySQL  Common fault analysis and countermeasures

Analysis on the wallet system architecture of Baidu trading platform

Wide table based data modeling application

Design and exploration of Baidu comment center

Data visualization platform based on template configuration