swagger

https://swagger.io

Knife4j对swagger进行封装，pom导入

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

使用方式

1. 导入knife4j的maven坐标

2. 配置类中加入knife4j相关配置

   package com.sky.config;
   
   /**
    * 配置类，注册web层相关组件
    */
   @Configuration
   @Slf4j
   public class WebMvcConfiguration extends WebMvcConfigurationSupport {
   
       /**
        * 通过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. 设置静态资源映射

   /**
    * 设置静态资源映射
    * @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. 全局配置信息(包含配置和资源映射)

   package com.sky.config;
   
   import com.sky.interceptor.JwtTokenAdminInterceptor;
   import lombok.extern.slf4j.Slf4j;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
   import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
   import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
   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;
   
   /**
    * 配置类，注册web层相关组件
    */
   @Configuration
   @Slf4j
   public class WebMvcConfiguration extends WebMvcConfigurationSupport {
   
       @Autowired
       private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;
   
       /**
        * 注册自定义拦截器
        *
        * @param registry
        */
       protected void addInterceptors(InterceptorRegistry registry) {
           log.info("开始注册自定义拦截器...");
           registry.addInterceptor(jwtTokenAdminInterceptor)
                   .addPathPatterns("/admin/**")
                   .excludePathPatterns("/admin/employee/login");
       }
   
       /**
        * 通过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;
       }
   
       /**
        * 设置静态资源映射
        * @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/");
       }
   }

常用注解

1. @API 用在类上，例如Controller，表示对类的说明
2. @ApiModel 用在类上，例如entity、DTO、VO
3. @ApiModelProperty 用在属性上，描述属性信息
4. @ApiOperation 用在方法上，例如Controller的方法，说明方法用途、作用