1, Foreword
As the most popular Java web development scaffold, Spring Boot is used by more and more developers to build enterprise RESTFul API interfaces. These interfaces will serve not only the traditional web side (b/s), but also the mobile side. In the actual development process, these interfaces should also be provided to the development and testing for relevant white box testing, so there is bound to be the problem of how to share and update API development interface documents in multi person cooperation.
Integrating documents with Swagger has the following advantages:
- Rich functions: support multiple annotations, automatically generate interface documents, and test API interface functions on the interface;
- Update in time: spend a little time writing comments in the development process, you can update API documents in time, which saves you worry and effort;
- Simple integration: by adding pom dependencies and simple configuration, you can publish API interface documents and interfaces embedded in the application at the same time without deploying independent services.
Next, we use Spring Boot to integrate Swagger to realize the functions of online API documents. In this paper, we use SpringFox Swagger2, version 2.9.2 (the latest version is 3.0.0, but in my test, the swagger-ui.html page has not come out. In https://mvnrepository.com/ You can also see that 2.9.2 is the most used version at present)
2, Create Spring Boot project
The development tool I use is IDEA. I can quickly create a Spring Boot project through IDEA. When creating, just check the web dependency option. It doesn't matter if I don't check it. The configuration in pom.xml is the same later. Note that when creating a project, the project name should be lowercase.
Add two dependencies of Swagger
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
3, Add configuration class
Add a swagger configuration class, create a new config package under the project, and add a SwaggerConfig configuration class SwaggerConfig.java.
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("on-line API file") .description("This is a restful api document of demo") .version("1.0") .build(); } }
The above has completed the configuration of Swagger. Is it very simple and easy.
4, Create a test Controller to verify the configuration
Add a controller, create a new controller package under the project, and add a HelloController.java.
package com.louis.springboot.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; /* Class annotation */ @Api @RestController public class HelloController { /* Method annotation */ @ApiOperation(value = "desc of method", notes = "") @GetMapping(value="/hello") public Object hello( @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) { return "Hello " + name + "!"; } }
5, Compile and run tests
Start the project, open the browser and visit: http://localhost:8080/swagger-ui.html to enter the swagger interface document interface.
It's convenient to manage the API interface and update the code in real time. You don't have to worry about writing interface documents.
Appendix: Swagger common notes
API | Use location |
@Api | Used on the controller class, indicating that this class is a resource of swagger |
@ApiOperation | It is used in the method of controller to represent the operation of an http request |
@ApiParam | Parameter annotation in method |
@ApiResponses | Used in the controller method |
@ApiResponse | Used in @ ApiResponses |
@ApiImplicitParams | Used in the controller method |
@ApiImplicitParam | Used in the @ ApiImplicitParams method |
@ApiModel | Used on the return object class |
There are many strange problems in WEB project development.