如何使用Swagger2

• 接口文档访问接口:http://localhost:8080/swagger-ui.html

分析和效果演示

• 分析
  
• 效果
  

配置

pom.xml

 <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>

配置类

• 实现WebMvcConfigurer 接口
• 要填自己的控制器位置路径
• 若打算关闭显示则在以下 return new Docket(DocumentationType.SWAGGER_2)最后面加.enable(false); (一般用于环境区分,线上环境就不显示)

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket productApi() {
        //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2).select()
                // 扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.edt.trip.controller"))
                // 定义要生成文档的Api的url路径规则
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                // 设置swagger-ui.html页面上的一些元素信息。
                .apiInfo(metaData());
    }

    private ApiInfo metaData() {

        return new ApiInfoBuilder()
                // 标题
                .title("SpringBoot集成Swagger2")
                // 描述
                .description("豪行天下项目接口文档")
                // 文档版本
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

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

}

使用

• 使用用户对象操作做演示

控制器

• 贴@Api(value = "用户资源", description = "用户资源控制器") 说明控制器
  

控制器方法

• 贴@ApiOperation(value = "注册功能", notes = "其实就是新增用户")说明方法
• 贴@ApiImplicitParams({ @ApiImplicitParam(value = "手机号", name = "phone", dataType = "String", required = true) }) 说明参数
  
• @ApiResponses({ @ApiResponse(code = 200, message = "用户注册成功") })
  • 用在@ApiResponses中，一般用于表达一个错误的响应信息(200相应不写在这里面)
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出的异常类
    
• 贴 @ApiIgnore 在接口方法上,表示不显示此接口在文档上

实体类

• 贴@Api(value = "用户",description = "平台注册用户模型")说明对象
• 贴@ApiModelProperty(value="昵称",name="nickName",dataType = "String",required = true) 说明属性
  

拦截处理

• 一些项目会有拦截器类拦截路径,所以要配置开放该swagger接口文档url
• 拦截器的类 重写以下addInterceptors方法即可

@Configuration
public class WebConfigurer extends WebMvcConfigurationSupport {

    @Resource
    private DateConverterConfig dateConverterConfig;

    @Resource
    private SecurityControlInterceptor securityControlInterceptor;

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        //定义排除swagger访问的路径配置
        String[] swaggerExcludes=new String[]{"/swagger-ui.html","/swagger-resources/**","/webjars/**"};
        securityControlInterceptor.init();// 初始化数据
        registry.addInterceptor(securityControlInterceptor).addPathPatterns("/**").excludePathPatterns(swaggerExcludes);
        super.addInterceptors(registry);
    }

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


    @Override
    protected void addFormatters(FormatterRegistry registry) {
        registry.addConverter(dateConverterConfig);
    }
}