Swagger的使用

Swagger

介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。

官网：https://swagger.io/

knife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

使用

1. 导入knife4j的maven坐标

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

2. 导入knife4j相关配置类

   @Configuration
   @EnableKnife4j
   @EnableSwagger2
   public class Knife4jConfig {
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.itoah.xxx.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("xx系统")
                   .version("1.0")
                   .description("xx系统接口文档")
                   .build();
       }
   }
   

3. 设置静态资源，否则接口文档页面无法访问(如果你配置了拦截器)，那么你需要将这些路径加入白名单

   registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
   registry.addResourceHandler("/favicon.ico").addResourceLocations("classpath:/META-INF/resources/");
   registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   

4. 在LoginCheckFilter中设置不需要处理的请求路径（如果你配置了登录验证）但想在不登陆时也能访问,那么你需要将下面这些路径加入白名单

                   "/swagger-resources",
                   "/v2/api-docs",
                   "/webjars/**",
                   "/doc.html"
   

常用注解

注解	说明
@Api	用在请求的类上，例如Controller，表示对类的说明
@ApiModel	用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性
@ApiOperation	用在请求方法上，说明方法的用途，作用
@ApilmplicitParams	用在请求方法上，表示一组参数说明
@ApilmplicitParam	用在@ApilmplicitParams注解中，指定一个请求参数的各个方面

例：