使用 swagger 2 生成 api 接口文档 实战

集成步骤

1、添加 pom

<properties>
        <swagger.version>2.9.2</swagger.version>
</properties>

 <dependencies>
<!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        
   </dependencies>      

2、添加配置类

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.xxx.web.controller"})
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("交付业务API文档")
                .description("交付逻辑项目")
                .contact(new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"))
                .version("V1.0")
                .build();

    }
}

3、使用注解配置

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
		@ApiModelProperty：描述一个model的属性

本人常用的注解：

• 方法

@GetMapping(value = "list", produces = "application/json; charset=UTF-8")
@ApiOperation("订单列表查询")
@ApiImplicitParams({
    @ApiImplicitParam(paramType = "query", name = "type", value = "业务类型", required = true, dataType = "Integer"),
    @ApiImplicitParam(paramType = "query", name = "status", value = "订单状态,默认值 0", required = true, dataType = "Integer")
    })
    public ResultInfo<PageInfo<OrderResponse>> list(@RequestParam(value = "type", defaultValue = "0") Integer type,@RequestParam(value = "status", defaultValue = "0") Integer status,) {
      
}

• domain

@ApiModel("disk 实体")
public class DiskResponse {

    @ApiModelProperty("磁盘序号")
    private Integer seq;
    @ApiModelProperty("磁盘容量")
    private Integer capacity;
 }

注解中有很多 属性，可以根据需要使用。

注意出现问题

当 添加一个 拦截器后， swagger就失效的，访问 swagger-ui.html

@@Configuration
public class InterceptorConfig extends WebMvcConfigurationSupport {
  //自定义一个 拦截器
}

网上资料也很多 继承WebMvcConfigurationSupport后自动配置不生效的问题及如何配置拦截器

继承WebMvcConfigurationSupport的过滤器导致Swagger地址不能访问

先记录下解决的方式：

@Configuration
public class InterceptorConfig extends WebMvcConfigurationSupport {

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MyInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/actuator/health/**")
                .excludePathPatterns("/v2/api-docs/**")
                .excludePathPatterns("/v2/api-docs-ext/**")
                .excludePathPatterns("/swagger-resources")
                .excludePathPatterns("/error/**")
                .excludePathPatterns("/webjars/**")
                .excludePathPatterns("/swagger-ui.html")
                .excludePathPatterns("/doc.html");
        super.addInterceptors(registry);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}