Guns——使用swagger生成api文档（三）

1.swagger介绍

swagger是用来自动生成相应api文档的一个插件，使用简单。

2.引入swagger依赖

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

3.配置相应的配置类

从下面代码可以清晰的看到配置详情，在生成api的时候有两种方法

• 第一种是通过扫描注解的方式生成api文档，自由度较高
• 第二种是通过扫描包的方式生成api文档，速度快，无需加注解（不同同时使用两种方法）

@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "guns", name = "swagger-open", havingValue = "true")
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
               // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                         //这里采用包含注解的方式来确定要显示的接口
                .apis(RequestHandlerSelectors.basePackage("cn.stylefeng.guns.modular.system.controller"))    //这里采用包扫描的方式来确定要显示的接口
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Guns Doc")
                .description("Guns Api文档")
                .termsOfServiceUrl("https://gitee.com/stylefeng/guns")
                .contact("stylefeng")
                .version("2.0")
                .build();
    }

}

4.注解的使用方法

@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方

1. header-->请求参数的获取：@RequestHeader
2. query-->请求参数的获取：@RequestParam
3. path（用于restful接口）-->请求参数的获取：@PathVariable
4. body（@RequestBody）
5. form（表单提交）

• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：参数的意思
• defaultValue：参数的默认值

5.配置相应的ui资源

由于正常的访问路径都会经过DispatchServlet，所以需要在web的配置类上配置相对应的静态资源（有两个），两个才构成一个完整页面

• 第一个是swagger的html文件
• 第二个是html所引用的其他资源文件

@Configuration
public class WebConfig implements WebMvcConfigurer {

    ...

    /**
     * 增加swagger的支持
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        if (gunsProperties.getSwaggerOpen()) {
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

    ...

}