Swagger使用小记

Swagger是一种框架，用于自动生成Restfull API的文档，而不用开发者自己编写文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

以下以SpringBoot 2.0.1中整合Swagger2.8.0为例.

1、Maven：

        <!-- swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2、建立Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    // 须不能被拦截的资源（包括请求的拦截、返回信息的拦截改造等），如不能被WebSecurity框架拦截
    public static final List<String> RESOURCE_PATTERNS = Arrays.asList("/swagger-ui.html", "/webjars/**", "/swagger-resources/**", "/api-docs", "/v2/api-docs");

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // API文档页面相关资源作为静态资源，以防止被拦截处理
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger-resources/**").addResourceLocations("classpath:/META-INF/resources/");
    }

    private ApiInfo apiBasicInfo = new ApiInfoBuilder().title("SSEducationAdmin Server API").description("Spring Boot REST API for SSEducationAdmin").version("0.0.1")
            .license("Apache License Version 2.0").licenseUrl("https://www.apache.org/licenses/LICENSE-2.0\"")
            .contact(new Contact("San Zhang", "https://localhost:8082/", "zhangsan1@xx.com")).build();

    private Parameter tokenHeaderParameter = new ParameterBuilder().name(BasicWebSecurityConfig.AUTHENTICATION_HEADER_NAME).description("接口调用认证及鉴权").modelRef(new ModelRef("string"))
            .parameterType("header").required(true).build();

    //通过Docket进行API分组，通常根据业务模块来分组，这样可在swagger ui上选择这些分组看对应的API
    @Bean
    public Docket allApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiBasicInfo).globalOperationParameters(Arrays.asList(tokenHeaderParameter)).groupName("所有接口").select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();
    }

    @Bean
    public Docket customerManageApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiBasicInfo).globalOperationParameters(Arrays.asList(tokenHeaderParameter)).groupName("客户管理接口").select()
                .apis(RequestHandlerSelectors.basePackage(CustomerAdmin_CustomerController.class.getPackage().getName()))// 指定扫描的包，其下Controller方法会生成文档
                .paths(PathSelectors.any()).build();
    }


}

若未配置分组，则默认会将所有 @Controller 修饰的类下的接口都扫描列出来。

需要注意的是：需要将一些swagger用到的接口或资源放行（包括请求的拦截放行、响应信息的拦截放行），相关路径为上述代码中变量 RESOURCE_PATTERNS 的内容（ "/swagger-ui.html", "/webjars/**", "/swagger-resources/**", "/api-docs", "/v2/api-docs" ），否则若被拦截通常会报如下错误：

 

 

 

3、Swagger使用：相关注解

　swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用 
• @ApiOperation：描述一个类的一个方法，或者说一个接口 
• @ApiParam：单个参数描述 
• @ApiModel：用对象来接收参数 
• @ApiProperty：用对象接收参数时，描述对象的一个字段 
• @ApiResponse：HTTP响应其中1个描述 
• @ApiResponses：HTTP响应整体描述 
• @ApiIgnore：使用该注解忽略这个API 
• @ApiError ：发生错误返回的信息 
• @ApiParamImplicitL：一个请求参数 
• @ApiParamsImplicit 多个请求参数

4、访问

http://localhost:8080/swagger-ui.html：（UI风格）

http://localhost:8080/v2/api-docs：（API风格）

 

 

参考资料：

1、SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2

2、https://blog.csdn.net/hu_zhiting/article/details/80462110