The most suitable SpringBoot+SSM project for novices "Sky Takeaway" actual combat - (4) Integrating Swagger

Dark Horse Programmer's latest Java project actual combat "Sky Takeaway", the most suitable SpringBoot+SSM enterprise-level Java project actual combat for novices.

Introduction to Swagger

Swagger is an open source API design tool that can be used to describe, design, develop and test RESTful APIs. It provides a standardized way to describe and present RESTful API, and can generate client and server code according to the API documentation, thus speeding up the development and deployment of API. With Swagger, developers can quickly build, test, and deploy RESTful applications using simple and powerful API interactions.

Spring has incorporated Swagger into its own standards and established the Spring-swagger project, now called Springfox. By introducing Springfox into the project, you can use Swagger very simply and quickly.

Different from YApi, Yapi is a tool used in the design phase to manage and maintain interfaces; Swagger is a framework used in the development phase to help back-end developers do back-end interface testing.

Knife4j is a Swagger front-end UI enhancement library, which generates API documents based on Swagger, and provides a more powerful UI interface and interactive experience. Knife4j provides a wealth of features, such as interface testing, interface online debugging, interface document export, etc., which greatly improves the efficiency and reliability of API development. Knife4j is developed based on SpringBoot and SpringMvc, supports the export of multiple document formats, and also supports custom UI styles and themes. Knife4j is open source and free to use and modify.

Integrate Swagger

1. Add Knife4j dependency in pom.xml:

   <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-spring-boot-starter</artifactId>
   </dependency>
   

2. Add Knife4j related configuration in the WebMvcConfiguration.java configuration class:

   /**
   * 通过knife4j生成接口文档
   * @return
   */
   @Bean
   public Docket docket() {
         
         
     ApiInfo apiInfo = new ApiInfoBuilder()
       .title("苍穹外卖项目接口文档")
       .version("2.0")
       .description("苍穹外卖项目接口文档")
       .build();
     Docket docket = new Docket(DocumentationType.SWAGGER_2)
       .apiInfo(apiInfo)
       .select()
       .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
       .paths(PathSelectors.any())
       .build();
     return docket;
   }
   

3. Set static resource mapping in WebMvcConfiguration.java, otherwise the interface documentation page cannot be accessed:

   /**
   * 设置静态资源映射
   * @param registry
   */
   protected void addResourceHandlers(ResourceHandlerRegistry registry) {
         
         
     registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
     registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }
   

4. Access the interface document path http://localhost:8080/doc.html in the browser :

   

5. Interface test, test login interface [login]:

   

Common Notes

The generated interface documents can be controlled through the annotations provided by Swagger to make the interface documents more readable. Commonly used annotations are as follows:

annotation	illustrate
@Api	Used on classes, such as Controller, to indicate the description of the class
@ApiModel	Used on classes, such as entity, DTO, VO
@ApiModelProperty	Used on attributes to describe attribute information
@ApiOperation	Used in methods, such as the method of Controller, to explain the purpose and function of the method

Next, use the above annotations to generate more readable interface documentation.

1. @ApiModify the EmployeeController.java class in the sky-server module, and add and comment on the methods on the class @ApiOperation:

   @Api(tags = "员工相关接口")
   public class EmployeeController {
         
         
   
       @PostMapping("/login")
       @ApiOperation(value = "员工登录")
       public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) 	{
         
         
           //..............
       }
   
       @PostMapping("/logout")
       @ApiOperation("员工退出")
       public Result<String> logout() {
         
         
           return Result.success();
       }
   
   }
   

2. Start the service: visit http://localhost:8080/doc.html