How do microservices aggregate API documents? This wave of show~

Today's article introduces how microservices are aggregated Swagger Realize interface document management .

The article list is as follows ：

Why do we need to aggregate ？

There are many micro service modules , If you don't aggregate documents , Then access... Of each service API Documents are required A separate Visit one Swagger UI Interface , Whether the client can accept ？

Anyway, as an obsessive-compulsive disorder, I can't accept .......

Now that we're using microservices , There should be A unified API Document entry .

How to aggregate ？

A unified document entry should obviously be aggregated into the gateway , adopt gateway The entry of is uniformly mapped to each module .

In this paper Spring Cloud Gateway polymerization Swagger Of The way Generate API file .

The case source code structure is as follows ：

This article only describes how to aggregate Swagger, About gateway 、 Registration center and other contents will not be introduced , If you don't understand, read Chen's previous article .

How individual services aggregate Swagger？

The single service here does not include a gateway , The gateway needs to be configured separately .

Single service aggregation is actually very simple , It's just plain Spring Boot Integrate Swagger, But there are many micro service modules , You can't integrate every micro suit , So you can customize a swagger-starter, After that, every micro service depends on this starter that will do .

The detailed steps are as follows ：

1、 establish swagger-starter

Customize starter I won't go into it here , It's all basic knowledge ;

The directory structure is as follows ：

1、 Add dependency

about Swagger Native UI Chen doesn't like the interface very much , So I used one that looked good UI Interface , Depends on the following ：

<!--swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
</dependency>

<!--swagger-ui   Here is a nice one ui Interface -->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

about UI Interface , Everyone has different aesthetics , Choose what you like .

2、 Automatic configuration class configuration Swagger

Chen is the of each service API Extract an attribute class from the information SwaggerProperties, Subsequently, you only need to specify it in the configuration file of each service .

@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
    public static final String PREFIX="spring.swagger";

    // package 
    private String basePackage;

    // Information about the author 
    private Author author;

    //API Information about 
    private ApiInfo apiInfo;

    @Data
    public static class ApiInfo{
        String title;
        String description;
        String version;
        String termsOfServiceUrl;
        String license;
        String licenseUrl;
    }
    @Data
    public static class Author{
        private String name;

        private String email;

        private String url;
    }
}

about Swagger The configuration of is actually very simple , It is divided into the following parts ：

1. API Document basic information configuration
2. Authorization information configuration （ be based on OAuth2 Authentication configuration ）

API Document configuration is nothing more than the basic information of the configuration document , For example, the document title 、 author 、 Contact information .....

The code is as follows ：

Authorization information configuration is also very simple , It is to configure a place where tokens can be placed in the request header of global information , The code is as follows ：

This corresponds to UI The interface is shown in the figure below ：

Just get token Set the token here .

Okay ,swagger-starter The key code is introduced , See the source code for detailed configuration .

The case source code has been uploaded GitHub, Focus on VX： Code ape technology column , Reply key ：9529 obtain ！

2、 Microservice reference swagger-starter

A single microservice reference is simple , Just add the following dependencies ：

<dependency>
  <groupId>cn.myjszl</groupId>
  <artifactId>swagger-starter</artifactId>
</dependency>

Next, you only need to configure... In the configuration file API Relevant information is enough , For example, the configuration of order service is as follows ：

Okay , At this point, the configuration of a single service is completed .

At this point, we can verify , Direct access ：http://localhost:3002/swagger-order-boot/v2/api-docs, The results are as follows ：

How do gateways aggregate Swagger？

The idea of gateway aggregation is very simple , Is to get the access address of the micro service from the route , Then put it together /v2/api-docs that will do .

Again, add Swagger The two dependencies of , as follows ：

<!--swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
</dependency>

<!--swagger-ui   Here is a nice one ui Interface -->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

establish GatewaySwaggerResourcesProvider Realization SwaggerResourcesProvider, Rewrite one of get Method , The code is as follows ：

The case source code has been uploaded GitHub, Focus on VX： Code ape technology column , Reply key ：9529 obtain ！

Okay , The gateway configuration is completed here .

The gateway is now started 、 Order 、 Inventory service , Direct access to gateway documentation ：http://localhost:3001/doc.html, The results are as follows ：

API Document easy to use function introduction

I have to say this one Swagger UI The interface is still relatively simple and easy to use , It's good for personal use .

1、 Search function

The search function in the upper right corner can search relevant interface information according to the interface description , Here's the picture ：

2、 Offline documents

You can copy documents directly MarkDown The form is transformed into Html perhaps PDF Generate offline documents , Here's the picture ：

3、 Token configuration

When accessing an interface that requires authentication , You can configure the token , In this way, the token will take effect globally , You don't have to configure every request , as follows ：

4、 Configure the cache

All configurations of this document , Including request parameters 、 Authorization tokens and other information are cached , In other words, configure once , The next time you open it, it exists by default .

5、 Global parameter configuration

For some global parameters , For example, the request header needs to carry the request client 、 Version number and other information , Can be configured in global parameters , as follows ：

summary

This article introduces microservice integration gateway aggregation Swagger file , Very practical in development .