Swagger使用说明

1 Swagger的出现

在前后端分离的项目中，后端开发者需要向前端或者其他后端开发者提供接口文档。实际工作中提供一份完整准确的接口文档是一件异常花费时间精力的事情。为了解决问题可以采用Swagger来提供在线的接口文档，通过在代码中写注解可以明显提升文档质量。

2 在项目中加入Swagger

• pom.xml
  在pom文件中添加添加Swagger依赖的jar包

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

• 配置文件
  编写Swagger配置文件并启用Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport{
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.css.gxb.repservices.control"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("标题")
                        .description("测试描述")
                        .version("1.0")
                        .contact(new Contact("","www.baidu.com","a_strategy@163.com"))
                        .license("接口文档")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restful风格，http://blog.csdn.net/forezp")
                .version("1.0")
                .build();
    }

}

3 常见的Swagger注解的使用

3.1 分类

本文按三个维度划分了Swagger注解，分类如下图所示：

3.2 注解使用说明

3.2.1 @Api

说明：

@Api：用在请求的类上，说明该类的作用
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"（亲测没什么用途）

示例：

结果：

3.2.2 @ApiModel、@ApiModelProperty

说明：

@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性

示例：

结果：

3.2.3 @ApiOperation

说明：

@ApiOperation："用在请求的方法上，说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"

示例：

结果：

3.2.4 @ApiImplicitParams、@ApiImplicitParam

说明：

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header 
            · query 
            · path
            · body
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

示例：

• 单个参数
  
• 多个参数
  
  注意：paramType必须和参数注解向匹配
  header --> @RequestHeader
  query --> @RequestParam
  path（用于restful接口）–> @PathVariable
  body -->@RequestBody
  form -->@RequestBody

结果：

• 单个参数
  
• 多个参数（没有做相应的实验，效果应该和单参数的差不多，后台都可以读到对应的参数值）
  略；

4 总结

其实归根到底，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。