Shulou(Shulou.com)06/02 Report--

This article introduces the relevant knowledge of "how to implement Java development SpringBoot integration interface document". In the operation of actual cases, many people will encounter such a dilemma, so let the editor lead you to learn how to deal with these situations. I hope you can read it carefully and be able to achieve something!

Swagger vs smart-doc

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

The code of Swagger is more intrusive.

It's easy to understand that in order for Swagger to generate interface documents, you have to add comments to the method or field, and there is code intrusion.

Native swagger does not support parameter grouping of interfaces

Native Swagger does not support interfaces that have parameter grouping. Although we can extend its components to support parameter grouping, it still needs to be developed and does not support the latest version of Swagger3.

For comparison, smart-doc generates interface documents based on interface source code analysis, completely achieving zero annotation intrusion, you only need to write according to java standard annotations, smart-doc can help you generate a simple 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 annotations, zero learning costs, and only need to write standard java comments to generate documentation.

Automatic derivation based on source code interface definition, powerful return structure derivation.

Spring MVC,Spring Boot,Spring Boot Web Flux (controller writing mode) is supported.

Support the derivation of the return of asynchronous interfaces such as Callable,Future,CompletableFuture.

Support JSR303 parameter verification specification on JavaBean and parameter grouping.

Some commonly used field definitions can generate valid simulation values.

Next, let's take a look at how smart-doc is integrated into SpringBoot.

SpringBoot integrated smart-doc

Smart-doc supports multiple ways to generate interface documents: maven plug-in, gradle plug-in, unit test (not recommended). Here, I use the generation based on maven plug-in, as follows:

Introduce dependency, choose the latest version com.github.shalousun smart-doc-maven-plugin 2.2.7. / src/main/resources/smart-doc.json Smart-Doc first experience

Focus on specifying the smart-doc profile smart-doc.json in configFile

Create a new profile 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.

Generate the corresponding interface document / / generate htmlmvn-Dfile.encoding=UTF-8 smart-doc:html by executing the maven command

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

Access interface documentation

After the API document is generated, we can view it through http://localhost:8080/doc/api.html. The results are as follows:

The students who see here may laugh, that's it? There's nothing! And you want me to replace Swagger?

Don't worry, you've just experienced the basic features of smart-doc, and then we'll enhance it by enriching the contents of smart-doc 's configuration files.

Function enhancement 1. Turn on debugging

An excellent API documentation tool must have debugging features. Smart-doc supports online debugging, and you only need to add the following configuration items:

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

Turn on the debug function through "createDebugPage": true, and directly put it under static/doc/ when generating smart-doc generation documents, so that you can directly start the program to visit the page http://localhost:8080/doc/index.html for development and debugging.

Some developers use [Open In Browser] to open debug pages generated by smart-doc directly in idea, and if you have to do so, cross-domain occurs when the front-end js requests a background interface. So you need to configure cross-domain on the backend.

Here, take SpringBoot2.3.x as an example to configure the backend cross-domain:

@ Configurationpublic class WebMvcAutoConfig implements WebMvcConfigurer {@ Bean public CorsFilter corsFilter () {final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource (); final CorsConfiguration corsConfiguration = new CorsConfiguration (); / * whether to allow requests with authentication information * / corsConfiguration.setAllowCredentials (true); / * allowed client domain names * / corsConfiguration.addAllowedOrigin ("*") / * client request headers that allow server access * / corsConfiguration.addAllowedHeader ("*"); / * allowed access method names, GET POST, etc. * / corsConfiguration.addAllowedMethod ("*"); urlBasedCorsConfigurationSource.registerCorsConfiguration ("/ * *", corsConfiguration); return new CorsFilter (urlBasedCorsConfigurationSource);}}

After enabling cross-domain, we can debug directly in the static interface page.

two。 Universal response body

In "how does SpringBoot unify the format of back-end returns? that's how old birds play!" In this article, we wrap all the returned values by implementing ResponseBodyAdvice to return a unified data structure ResultData to the frontend. We need to make it have this feature in the API document and append the configuration content to the configuration file:

{"responseBodyAdvice": {--General response body "className": "com.jianzh6.blog.base.ResultData"}}

3. Custom Header

In front-end separation projects, we generally need to set a request header when requesting an interface, such as token,Authorization, etc. The backend judges whether it is a legitimate user of the system according to the request header, which is also supported by smart-doc at present.

Continue to append the following configuration content to the smart-doc configuration file smart-doc.json:

"requestHeaders": [/ / set request header If there is no requirement, you can not 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": whether false,// must be "since": "-" / / what version of the modified request header "pathPatterns": "/ smart/say", / / only url that begins with / smart/say will have this request header "excludePathPatterns": "/ smart/add,/smart/edit" / / url=/app/page/ will not have this request header}]

The effect is as follows:

4. Parameter grouping

Demonstrate smart-doc 's support for parameter grouping

For new operations, age and level are required, while sex is not required.

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

From the above effect, you can see that smart-doc fully supports parameter grouping.

5. Idea configure doc

Custom tag is not prompted automatically by default and needs to be set by the user in idea. It can be used after it is set up. Take setting mock tag customized by smart-doc as an example, the setting operations are as follows:

6. Complete configuration

Complete configuration is attached. If you need other configurations, you can refer to wiki to introduce it 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.jianzh6.blog.smartdoc.*", "errorCodeDictionaries": [{"title": "title", "enumClassName": "com.jianzh6.blog.base.ReturnCode" "codeField": "code", "descField": "message"}], "responseBodyAdvice": {"className": "com.jianzh6.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"}]} "how to implement Java Development SpringBoot Integrated Interface document" ends here Thank you for your reading. If you want to know more about the industry, you can follow the website, the editor will output more high-quality practical articles for you!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.