How does the back end provide API s at work? swaggo is good

Last time we briefly shared Casbin of GO permission management, which generally refers to the security rules or security policies set according to the system

• Shared what rights management is
• What is Casbin
• Characteristics of caspin
• Application case of Casbin

If you are interested, we can discuss and share more deeply in the future. Welcome to see the article Casbin of GO permission management

Today, let's share how our back-end partners provide API s efficiently in our work?

API is composed of a set of definitions and protocols, which can be used to build and integrate application software with enterprises

API is the application programming interface

I believe many friends like to write documents. They may use markdown to write down the interface. The relevant person in charge has agreed on a fixed template

Some will use simple text files, and some big brothers may not even output any documents, so they can't live the second episode in the TV series

What about the test?

Generally, the postman tool is used to set parameters against the interface, conduct self-test, or write scripts for test

However, it's too troublesome. You have to spend too much time writing the interface. Each time you modify the interface, you have to modify the corresponding document. It's quite cumbersome and a little anti human

Let's take a look at how the GO swaggo tool solves the above problems and what operations it has

What is swaggo?

Is a tool designed to automatically convert golang annotations to Swagger 2.0 documents

What is Swagger?

Swagger is a Web service

It is a normative and complete framework that can generate, describe, invoke and visualize RESTful style documents

So what is his advantage?

It has the following two advantages:

• Support API to automatically generate synchronized online documents

After using Swagger, you can generate documents directly through code, and you no longer need to write interface documents manually

• Web page online testing API is provided

The documentation generated by Swagger also supports online testing

Once the parameters and formats are set, you can directly enter the values corresponding to the parameters on the interface to test the interface online. It's really delicious to use

How do we use swaggo?

Let's write a basic case of your swaggo, which is roughly divided into the following steps:

• Install swag for automatic document generation

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

• We need to use the following two packages. We can know that we still use go mod by default. After writing the code, we can go build directly, and the used packages will be pulled down

The first one is gin swagger. It's convenient for us to use gin to play swagger. We have also shared the use of gin with you before. If you are interested, you can check the article Gin actual combat drill

go get github.com/swaggo/gin-swagger

The second is the swagger built-in file

go get github.com/swaggo/gin-swagger/swaggerFiles

• You need to simply use the gin framework

Let's start coding a simple little 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"
)

// Handle function for 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))

   // Routing packets, first version of API v1
   v1 := r.Group("/api/v1")
   {
      v1.GET("/hello", Hello)

   }

   // The listening port is 8888
   r.Run(":8888")
}

The above code is roughly divided into these steps:

• Use r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) to Handler registration
• Write a custom route and corresponding method
• Listen to the specified address and port

After the above code is written, we can use and main Initialize a go module in the same level directory of go, and then go build to run the program

go mod init myswa
go build

The above command go mod init myswa, the initialization module is myswa, and the local package paths imported into us in the future need to start with myswa

After executing the above command, a myswa module will be initialized. After executing go build, the relevant packages used will be pulled down and compiled

After successful compilation, type in the browser:

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

If you see the following error print message, the reason is that the docs of swag is not installed

Here you can check whether swag is successfully installed

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

After the installation is successful, you can use swag init for initialization. Swag will help us generate corresponding docs. For example, my code directory is like this

This is why one of the packages we imported is_ "myswa/docs"

Type again in the browser:

http://127.0.0.1:8888/swagger/index.html , if the following effects can be viewed, it is successful

Add comments

We're in main Go file, add some comments, and then see the effect, for example

package main

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

// Handle function for 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: it's the 26th day of the revision challenge, and the theme is 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))

    // Routing packets, first version of API v1
    v1 := r.Group("/api/v1")
    {
        v1.GET("/hello", Hello)

    }

    // The listening port is 8888
    r.Run(":8888")
}

After adding comments, perform the following 3 steps:

• Delete the previously generated docs directory
• Again in main Execute swag init under the go peer directory to generate the latest document
• Execute go run main Go, browser access http://127.0.0.1:8888/swagger/index.html We can see the following effects

At this point, check the generated docs directory to see what the specific file contents are?

These are automatically generated

my_swa/docs/swagger.json is as follows

{
    "swagger": "2.0",
    "info": {
        "description": "The 26th day of the Gengwen challenge, the theme is 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 is as follows:

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: The 26th day of the Gengwen challenge, the theme is Swagger
  termsOfService: https://juejin.cn/user/3465271329953806
  title: Xiaomotong Swagger  API
  version: "1.0"
paths: {}
swagger: "2.0"

The data displayed in the actual UI comes from the above two files

For the keywords in the above notes, let's make a table

Let's add corresponding comments to the function to see the effect

// @Summary hello world
// @Who do you say hello wrold to
// @Tags challenge test
// @Accept json
// @Param name query string true "specific name"
// @Success 200 {string} string "{"msg": "hello xxx"}"
// @Failure 400 {string} string "{"msg": "NO name"}"
// @Router /hello [get]
// Handle function for gin Hello
func Hello(c *gin.Context) {
   name := c.Query("name")
   c.JSON(http.StatusOK, gin.H{"msg": "hello wrold" + name})
}

After adding comments, perform the following 3 steps:

• Delete the previously generated docs directory
• Again in main Execute swag init under the go peer directory to generate the latest document
• Execute go run main Go, browser access http://127.0.0.1:8888/swagger/index.html We can see the following effects

Let's do a basic test on the page, fill in the name, execute and see the effect

Well, the test was successful

If such documents are given out, it will be very friendly to the front end, and there will be no increase in our workload. When writing code, please write comments

release

After development, it is impossible to bring your own api documents when publishing the version. This should not be

Therefore, we can control whether to compile the document by building tag. Leave a suspense here. Interested friends can try it

Interested friends, you can paste the above code locally, install the corresponding library, execute it and see the effect. It's really easy to use. I hope it can help you

summary

• What is swaggo
• What is swagger
• How to use swaggo
• How to test swaggo

Welcome to like, follow and collect

My friends, your support and encouragement are the driving force for me to insist on sharing and improve quality

OK, that's all for this time. Next time, GO's timer timer and scheduled task cron

Technology is open, and our mentality should be open. Embrace change, live in the sun and strive to move forward.

I'm Nezha, the Little Devil boy. Welcome to praise and pay attention to the collection. See you next time~