SpringBoot integrates smart doc to generate interface documents

However, when I came into contact with smart doc, another interface documentation tool, I think it is more suitable for integration in the project than Swagger and is more suitable for old birds. Today, we will introduce the use of smart doc component as a supplement to the old bird series.

swagger vs smart-doc

First, let's take a look at the main problems of Swagger components:

  1. Swagger's code is very intrusive

    This is easy to understand. In order for Swagger to generate interface documents, corresponding annotations must be added to methods or fields. There is code intrusion.

  2. Native swagger does not support parameter grouping of interfaces

    For the interface with parameter grouping, the native Swagger does not support it. Although we can support parameter grouping by extending its components, it needs to be developed after all, and it does not support the latest Swagger3 version.

That's for comparison, smart doc   It is based on the interface source code analysis to generate the interface document, which completely achieves zero annotation intrusion. You only need to write the annotation according to the java standard, and smart doc can help you generate a simple and clear markdown or a static html document like GitBook style. Official address: https://gitee.com/smart-doc-team/smart-doc

Briefly list the advantages of smart doc:

  • Zero annotation, zero learning cost, only need to write standard java annotations to generate documents.

  • Automatic derivation based on source code interface definition and powerful derivation of return structure.

  • Support Spring MVC,Spring Boot,Spring Boot Web Flux(controller writing mode).

  • Support the derivation of callable, future, completable future and other asynchronous interface returns.

  • Support JSR303 parameter verification specification on JavaBean and parameter grouping.

  • Some common field definitions can generate valid analog values.

  • ...

Next, let's take a look at how to integrate smart doc in SpringBoot.

SpringBoot integration smart doc

Smart doc supports the generation of interface documents in many ways: maven plug-in, gradle plug-in and unit test (not recommended). Here I use the generation based on maven plug-in. The steps are as follows:

  1. Introduce dependency version, and select the latest version

<!--introduce smart-doc-->
<plugin>
  <groupId>com.github.shalousun</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>2.2.7</version>
  <configuration>
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <projectName>Smart-Doc First experience</projectName>
  </configuration>
</plugin>

Focus on specifying the smart doc configuration file smart doc.json in the configFile

  1. Create a new configuration file smart-doc.json

{
  "outPath": "src/main/resources/static/doc"
}

Specify the document path generated by smart doc. For other configuration items, please refer to the official wiki.

  1. Generate the corresponding interface document by executing the maven command

//Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:html

Of course, it can also be generated through the maven plug-in in idea

 

  1. Provider documentation

After generating the interface document, we pass http://localhost:8080/doc/api.html The results are as follows:

 

See the students here may laugh, that's it? Nothing! Does this want me to replace Swagger?

Don't worry. I just experienced the basic functions of smart doc. Next, we will enhance the functions of smart doc by enriching its configuration file.

Function enhancement

1. Start commissioning

An excellent interface documentation tool must have debugging functions. Smart doc supports online debugging. Only the following configuration items need to be added:

{
  "serverUrl": "http://localhost:8080",       --  server address
  "allInOne": true,                -- Whether to merge documents into one file is generally recommended true
  "outPath": "src/main/resources/static/doc",  -- Specifies the output path of the document
  "createDebugPage": true,           -- Open test
  "allInOneDocFileName":"index.html",      -- Custom document name
  "projectName": "First acquaintance smart-doc"        -- entry name
}

Use "createDebugPage": true to enable the debug function and put it directly under static/doc / when generating smart DOC documents, so that you can directly start the program to access the page http://localhost:8080/doc/index.html Develop and debug.

Some developers directly use [Open In Browser] in idea to open the debug page generated by smart doc. If they have to do this, cross domain occurs when the front-end js requests the background interface. Therefore, you need to configure cross domain on the back-end.

Here, take springboot 2.3. X as an example to configure the backend cross domain:

@Configuration
public class WebMvcAutoConfig implements WebMvcConfigurer {

    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /* Allow requests with authentication information  */
        corsConfiguration.setAllowCredentials(true);
        /* Allowed client domain name  */
        corsConfiguration.addAllowedOrigin("*");
        /* Client request header to allow server access  */
        corsConfiguration.addAllowedHeader("*");
        /* Allowed method name, GET   POST, etc  */
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

After cross domain is enabled, we can debug directly in the static interface page.

2. General responder

In“ How does SpringBoot unify the back-end return format? Old birds play like this! ”In this article, we wrap all the returned values by implementing ResponseBodyAdvice and return the unified data structure ResultData to the front end. We need to make it also have this function in the interface document and add the configuration content to the configuration file:

{
  "responseBodyAdvice":{            -- Universal responder
    "className":"com.jianzh5.blog.base.ResultData"
  }
}

3. Customize Header

In the front end and back end separation project, we generally need to set a request header when requesting the interface, such as token, Authorization, etc... the back end determines whether it is a legal user of the system according to the request header. At present, smart doc also supports it.

Continue to add the following configuration contents to the smart doc configuration file smart doc.json:

"requestHeaders": [ //Set the request header. If there is no requirement, it can not be set
    {
      "name": "token",//Request header name
      "type": "string",//Request header type
      "desc": "Custom request header - token",//Request header description information
      "value":"123456",//Do not set default null
      "required": false,//Is it necessary
      "since": "-",//What version of change request header is added
      "pathPatterns": "/smart/say",//Only with / smart/say   The first url will have this request header
      "excludePathPatterns":"/smart/add,/smart/edit" //  url=/app/page / will not have the request header
    }
]

The effects are as follows:

 

4. Parameter grouping

Demonstrate smart Doc's support for parameter grouping

When adding an operation, age and level are required, and sex is not required.

When editing, id, appid, leven are required, and sex is not required.

From the above results, we can see that smart doc fully supports parameter grouping.

5. idea configuration doc

Custom tags are not automatically prompted by default and need to be set in idea. After setting, they can be used. The following is an example of setting smart doc custom mock tag s. The setting operations are as follows:

6. Complete configuration

The complete configuration is attached. If you need other configurations, you can refer to the wiki to introduce them yourself.

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName":"index.html",
  "projectName": "First acquaintance smart-doc",
  "packageFilters": "com.jianzh5.blog.smartdoc.*",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.jianzh5.blog.base.ReturnCode",
    "codeField": "code",
    "descField": "message"
  }],
  "responseBodyAdvice":{
    "className":"com.jianzh5.blog.base.ResultData"
  },
  "requestHeaders": [{
    "name": "token",
    "type": "string",
    "desc": "Custom request header - token",
    "value":"123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns":"/smart/add,/smart/edit"
  }]
}

Summary

In fact, there is nothing to summarize. Smart doc is very simple to use and the official documents are very detailed. As long as you can write standard java comments, you can generate detailed interface documents for you. (if you say you can't write comments, this article may not be suitable for you)   Moreover, after introducing smart doc, developers can be forced to write comments for the interface to ensure that there will be no great difference in team code style.

Tags: Java Spring Spring Boot

Posted on Thu, 25 Nov 2021 22:55:11 -0500 by mattdarnold