Spring Boot 集成 Swagger2

Swagger是一款让你更好的书写API文档的框架。同时可以实现API文档的在线查看和测试工作。

1. 添加Maven依赖

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

swagger2的版本请到这里查看。
2.新建SwaggerConfig.java类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的controller包名"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api文档")
                .description("restful 风格接口")
                .version("1.0")
                .build();
    }
}

使用@EnableSwagger2开启swagger配置。
apiInfo()方法返回swagger的描述信息。
api()返回swagger的配置信息。
select()方法返回ApiSelectorBuilder的实例，用于控制哪些接口需要暴露给swagger来显示。
apis()配置需要展示的包路径。
paths() api选择器选择包路径下任何api显示在文档中。
useDefaultResponseMessages()不使用默认包的response信息。
下面就可以访问http://localhost:8080/swagger-ui.html来查看效果了。

[email protected]

PS：如果不能正确访问swagger-ui.html界面，可以实现interface WebMvcConfigurer。

@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/");
}

3、Controller中的处理
我们看看下面几个注解

//接口信息描述
@ApiOperation
//多个请求参数的处理
@ApiImplicitParams
//具体单个参数的信息描述
@ApiImplicitParam

下面看看具体使用：

@ApiOperation(value="获取SOP分页列表", notes = "获取SOP分页列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "_page", value = "当前页数", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "_limit", value = "分页item数量", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "sopName", value = "SOP名称", dataType = "String"),
            @ApiImplicitParam(name = "status", value = "SOP状态", dataType = "Integer"),
    })
    @RequestMapping(method = RequestMethod.GET, produces = "application/json; charset=utf-8")
    public Result> getSOPList(@RequestParam(name = "_page") Integer page,
                                              @RequestParam(name = "_limit") Integer limit,
                                              @RequestParam(required = false) String sopName,
                                              @RequestParam(required = false) Integer status) throws Exception {
        ···
        return null;
    }

看到这里应该就很清晰了，具体就不详细描述了。让我们看看具体效果。

[email protected]

至此，Spring Boot集成swagger2基本已完成。