Swagger2的使用及注意事项

一、Swagger的主要作用有两方面：

1、生成在线文档，通过注解方式生成在线文档，方便在定义修正接口时直接修改接口文档；

2、对接口文档在线测试，不用在输入接口地址以及里面的参数对象，可以很方便的对在线接口测试。

二、 Swagger的使用方法如下：

1、引入springfox-swagger2的jar包依赖

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

2、增加swagger配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
    * 根据配置读取是否开启swagger文档，针对测试与生产环境采用不同的配置
    */
    @Value("${swagger.enable}")
    private boolean isSwaggerEnable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isSwaggerEnable)
                .apiInfo(apiInfo()).select()
                // 对所有该包下的Api进行监控，如果想要监控所有的话可以改成any()
                .apis(RequestHandlerSelectors.basePackage("com.sanchi.test"))
                // 对所有路径进行扫描
                .paths(PathSelectors.any())
                .build();
    }

    /**
    * @return 生成文档说明信息
    */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Sanchi test API文档")
                .description("接口文档")
                .termsOfServiceUrl("http://sanchips.github.io")
                .version("1.0.0").build();
    }
}

三、实际使用中注意事项

最近同时在使用时出现过下面两种问题导致swagger接口调试失败， 主要是接口配置的细节问题，但它不能正常工作时也要花几个小时排查。

1、swagger配置中basePackage参数没指定，参数拼写配置失误这个参数设置为"" ，结果swagger能正常扫描controler中的接口，但在测试时报错：……Invalid name……（代表省略的其它报错信息）。

2、指定了swagger的访问路径，但这个路径拼写错误，比如真实接口路径为/service/rs/……，但swagger中指定的访问路径为services/rs/……，导致接口测试时报404，找不到对应的接口地址，开始还以为api接口没生成生成，后来对比才发现因为指定的swagger的访问前缀url有问题。要注意少犯这种非智力错误，细心配置验证使用至少能节省开发半天时间。