Build an automated and centrally managed API Document Center for spring boot based microservice architecture

Time:2021-9-16

brief introduction

This article will explain how to build a set of API document center with automatic release and centralized management by using the tools provided by parliament developed by me and swagger and keyhole software.

Background introduction

Projects such as spring boot and spring cloud provide great convenience for us to build a micro service architecture. However, one of the disadvantages of microservice architecture is that it increases the complexity of governance.
As we all know, each application in the microservice architecture is developed and deployed independently. When the number of microservices reaches a certain number, it is more and more difficult to centrally manage API documents.
In order to reduce documentation pressure, many spring boot project sets use swagger to automatically generate API description pages. However, swagger does not solve the problem of centralized API control. Each team must clearly know the swagger page address of other teams, which is bound to complete the maintenance cost. This is also the original intention of the parisement project.

Solution

I developed a simple API document center server, Parliament. Parliament integrates the swagger UI for displaying and debugging APIs.
KHS spring boot publish swagger starter developed by keyhole software is used for API information release. It should be noted that there are several bugs in the original KHS spring boot publish swagger starter. Please use it temporarily
The version I provide.

The logic behind this is:

  1. Swagger2 is responsible for generating API descriptions,

  2. When the spring boot application starts each time, the API description is sent to the parliament server through KHS spring boot publish swagger starter.

  3. The parallelism server stores and sorts out API descriptions, and provides UI presentation to various team developers.

In this way, we have a centralized and automated API document center.

Start building

Before deploying parliament, we need to install mongodb. How to install and configure mongodb is beyond the scope of this article. After mongodb is installed, perform the following steps.

1. Deploy parliaments

$git clone https://github.com/burnettzhong/parliament.git
$cd parliament

modifyapplication.propertiesTo configure the data source, please modify it according to the actual mongodb information:

spring.data.mongodb.host = {MongoDB address}
spring.data.mongodb.database = {MongoDB database name}
spring.data.mongodb.port = {MongoDB port}

Build and start the assembly:

$mvn package && java -jar target/Parliament-1.0.0.jar

You can open it nowhttp://localhost:8080/index.htmlOf course, it’s basically a blank page, because we haven’t released any API information to Parliament yet.

2. Let spring boot applications publish API information

Here we need to add two dependency libraries, one is swagger2 of spring fox, and the other is KHS spring boot publish swagger starter.

be careful: please do not use the KHS spring boot publish swagger starter from keyhole software, which has two bugs. Only when they merge our pull request can they be used directly.

  1. Before keyhole software is updated in Maven public library, we need to manually install my version (1.0.2) into the local Maven Library:

    git clone https://github.com/burnettzho…
    cd khs-spring-boot-publish-swagger-starter
    mvn clean install

  2. Add swagger2 and KHS spring boot publish swagger starter dependencies in spring boot applications

    <dependency>

    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>

    </dependency>
    <dependency>

    <groupId>com.keyholesoftware</groupId>
    <artifactId>khs-spring-boot-publish-swagger-starter</artifactId>
    <version>1.0.2</version>

    </dependency>

  3. Configure the assembly address in application.yml or application.properties:

    swagger:

    publish:
        publish-url: http://{Parliament server address}/swagger/publish/
        swagger-url: http://127.0.0.1:${server.port}/v2/api-docs        
    

There are two addresses here. Publish URL is the deployment address of our Parliament,; Swagger URL is to obtain the API description address. Generally speaking, it is the application address.

  1. Finally, configure the spring boot application through annotations:

    @EnableSwagger2
    @PublishSwagger
    public class ServiceApplication {

    ...

    }

@EnableSwagger2Enable swagger2 to generate API descriptions,@PublishSwaggerLet the application publish the API description JSON to the assembly at startup.

Swagger2 provides rich functions for the configuration described by the API. Please refer toSpringfox Reference Documentation

At this point, all installation and deployment are completed. After starting the configured spring boot application, open it againhttp://localhost:8080/index.htmlYou can see our API information.
According toBase path of APIFor classification, click a base path to view more detailed API information (swagger UI is used here).

Postscript

  1. If necessary, you can register parlance as a micro service in euraka or zookeeper.

  2. Because parliaments are mainly used in the intranet, there is no security verification at present. Application authentication and user management will be introduced in the future.

  3. In the future, parallelism will also increase the function of API usage statistics and improve the overall API governance.

Welcome to pay attention and contribute code tohttps://github.com/burnettzho…

Recommended Today

OC basis

IOS development interview essential skills chart.png What are objects and what are the objects in OC? An object is an instance of a class; Is an instance created through a class, which is generally called an instance object; Common objects in OC include instance objects, class objects, and metaclass objects; What is a class? What […]