Exploring API blueprint interface document generation and interface simulation

Time:2021-9-27

preface

I found a very niubility thing today__ API Blueprint__, Give the official website firsthttps://apiblueprint.org/。 The following is the introduction given on the official website:

API Blueprint. A powerful high-level API description language for web APIs.

What can this do? According to the syntax of API blueprint (similar to markdown), we can use the ecological chain tool:

  1. Generate API interface document
  2. Analog interface before you write any code
  3. To be studied

For__ 1__ Because previous research tools such as Swagger still focus on writing the interface documents for a while, the Swagger was chosen at that time, and it was also very good at that time. The last interface document could also return data, but the problem is that writing JSON documents that rely on Swagger is a problem. The official support syntax is yaml (if markdown is so good). It hurts to manually maintain JSON documents of all interfaces directly. Finally, I found that a sosoapi can generate JSON documents that swagger depends on, but it is not open source!!! Therefore, using API blueprint syntax as the interface document writing standard is indeed a good choice.

Post swagger’s official websitehttp://swagger.io/

Secondly, the most powerful thing about API blueprint is what I once imagined: first formulate the interface data structure, and then simulate the interface response through this data structure. Then the students on the client side and the students on the back end can develop in parallel. The students on the client side no longer have to wait until the students on the back end have developed the interface, The back-end students can seamlessly switch to the real code after development.

on trial

  • Tool selection

After looking at the dazzling tools under the ecological chain, I first chose a tool developed by gosnowboard

  • install
//Installed under Linux, version v0.5.0 is installed here
wget https://github.com/subosito/snowboard/releases/download/v0.5.0/snowboard-v0.5.0.linux-amd64.tar.gz
tar -zxvf snowboard-v0.5.0.linux-amd64.tar.gz
./snowboard -h

//Installation under mac
$ brew tap subosito/packages
$ brew install snowboard
  • Write the first interface document
  1. Create a new. APIB suffix file api.apib

Recommended API blueprint syntax plug-in: language API blueprintFor example, atom

  1. Write interface documentation
//Example
# API
## GET /v1/message
+ Response 200 (application/json)
    {
        "status":"OK",
        "result":
        {
            "lists":[
                {"id":666},
                {"id":888}
                ],
            "count":10
        }
    }
  1. Generate interface document HTML page
//Command
./snowboard html -i api.apib -o api.html -s

visithttp://127.0.0.1:8088/
Exploring API blueprint interface document generation and interface simulation

  1. Enable interface emulation
//Command
./snowboard mock -i api.apib

//Return
Mock server is ready. Use 127.0.0.1:8087
Available Routes:
GET    200    /v1/message

visithttp://127.0.0.1:8087/v1/message
Exploring API blueprint interface document generation and interface simulation

epilogue

Isn’t it a very good thing, a sharp tool to improve production efficiency, ha ha ~ I just learned today….. Look, it still has many tools, including those used in combination with swagger. Follow up research is slow. Today, I had a fresh breath ~

Exploring API blueprint interface document generation and interface simulation