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

This article mainly explains "Spring Boot integration Swagger2 how to build API documents", the content of the article is simple and clear, easy to learn and understand, the following please follow the editor's ideas slowly in depth, together to study and learn "Spring Boot integration Swagger2 how to build API documents" bar!

What is Swagger

Swagger is an interface description language, which is mainly used to generate, describe, invoke and visualize RESTful-style Web service interface documents. Previous projects may have been more often not developed separately at the same time, so the interface documentation may not be that important. But now the mainstream projects are basically separated from the front and rear ends, if the front and rear ends do not communicate well, it may lead to the interface documents not updated in time, resulting in some unnecessary trouble. Generally speaking, Swagger is to help us write interface documents. It can not only automatically generate real-time interface documents, but also generate test cases, which is convenient for us to test.

Swagger mainly provides the following open source tools:

1.Swagger Editor

Swagger provided by the editor, mainly used to edit Swagger description file, support real-time preview description file updated effect, similar to our Markdown editor, the left side of the preparation of source code, the right side can be real-time preview. The editor is not only available online, but also supports local deployment.

2.Swagger UI

Provides a visual UI page that displays the description file of Swagger. The caller and test of the interface can look up the relevant information of the interface through this page and conduct a simple interface request test.

3.Swagger Codegen

By using this tool, the description file of Swagger can be generated into interface documents in the form of HTML and CWIKI, as well as code for servers and clients in many different languages.

4.Swagger UI

The tool that usually deals with us most is Swagger UI, which is mainly used to display interface documents. The interface description document is automatically generated according to the description set in our code according to the Swagger specification. A simple example is as follows:

Second, Spring Boot integrates Swagger1. Create a Spring Boot project

After a brief introduction to Swagger above, let's take a look at how to use Swagger in a Spring Boot project.

First you need to create a simple Spring Boot project, if you don't know how to create it

The created project APIs are as follows:

two。 Introduce dependency

After you have created the Spring Boot project, you need to configure the project pom.xml file to introduce the dependencies of Swagger.

Io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.23. Build Swagger configuration class

After introducing dependencies, the next step is to build the configuration class for Swagger.

Package com.cunyu.springbootswaggerdemo.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;/** * Created with IntelliJ IDEA. * * @ author: village Yuyao * @ version: springboot-swagger-demo * @ package: com.cunyu.springbootswaggerdemo.config * @ className: Swagger2Configuration * @ createTime: 22:21 * @ email: 747731461@qq.com * @ Wechat: cunyu1024 * @ official account: village Yuyao * @ website: https://cunyu1943.github.io * @ description: * / @ Configuration@EnableSwagger2public Class Swagger2Configuration {/ * configure Swagger2 * register a Bean attribute * enable (): whether to enable Swagger Enable to access in the browser * groupName (): to configure the grouping of API documents * / @ Bean public Docket docket () {return new Docket (DocumentationType.SWAGGER_2) .apiInfo (apiInfo ()) .enable (true) .groupName ("v1") .select () / / filter path / / .filter (PathSelectors.ant ()) / / specify the scanned package .apis (RequestHandlerSelectors.basePackage ("com.cunyu.springbootswaggerdemo.controller")) .build () } private ApiInfo apiInfo () {/ * author Information * / Contact contact = new Contact ("Village Yuyao", "https://cunyu1943.github.io"," 747731461@qq.com ") Return new ApiInfo ("Swagger Test Interface document", "Spring Boot Integrated Swagger Test Interface document", "v1.0", "https://cunyu1943.github.io", contact, Apache 2.0" "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList () }} 4. Write an interface

After configuring Swagger, add a simple interface to our project. Here we take a simple interface with and without parameters as an example.

Package com.cunyu.springbootswaggerdemo.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;/** * Created with IntelliJ IDEA. * * @ author: village Yuyao * @ version: springboot-swagger-demo * @ package: com.cunyu.springbootswaggerdemo.controller * @ className: SwaggerDemoController * @ createTime: 22:21 * @ email: 747731461@qq.com * @ Wechat: cunyu1024 * @ official account: village Yuyao * @ website: https://cunyu1943.github.io * @ description: * / @ Api@RestControllerpublic Class SwaggerDemoController {@ ApiOperation (value = "hello world interface") @ GetMapping ("hello") public String hello () {return "hello world" } @ ApiOperation (value = "reference interface") @ PostMapping ("demo") public String demo (@ ApiParam (name = "name", value = "Village Yuyao", required = true) String name) {return "hello,"+ name;}} 5. View and test the interface

After completing the above steps, we start the project and then access the following address in the browser to access the interface document of our project.

Http://localhost:8080/swagger-ui.html

After visiting the address above, if the following interface appears, it means that we have succeeded in integrating Swagger2 with Spring Boot.

Click on a specific interface, and you will have some details of this interface, as shown in the following figure, which generally includes:

Interface request mode

Interface request path and description

API request parameters

Interface response

If we want to do a simple test, click Try it out at the top right of the figure above, and then we can edit the value of the request parameter. After editing, click the Execute below to view the returned value of the API.

Take the interface I gave as an example. I passed in a parameter name, and then executed the API demo. Finally, I will return the result of hello,name, where name is the parameter value I passed. Here I passed the value of Village Yuyao, so the result should get hello and Village Yuyao. You can see that the corresponding result is returned to me in the Swagger test, indicating that our interface test is successful!

Note:

If the following error occurs during the consolidation process:

Org.springframework.context.ApplicationContextException:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

This may be due to the high version of SpringBoot. When I wrote this article, I used SpringBoot 2.6.2 at the beginning, so this error occurred, but when I downgraded SpringBoot to 2.5.6, the error no longer occurred. So if you have this problem, you can also try to lower the SpringBoot version to solve it.

Thank you for reading, the above is the "Spring Boot integration Swagger2 how to build API documents" content, after the study of this article, I believe you on the Spring Boot integration Swagger2 how to build API documents have a deeper understanding of this problem, the specific use of the need for you to practice and verify. Here is, the editor will push for you more related knowledge points of the article, welcome to follow!

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.