1.为什么使用swagger?

由于系统接口众多，细节复杂，高质量创建接口文档困难。随着需求的变化，接口修改的同时，接口文档必须修改。否则，系统接口和文档不一致。

swagger让维护文档和修改代码整合为一体，在修改代码逻辑的同时方便的修改文档说明。另外Swagger2提供页面测试功能来调试每个API。

2.swagger使用：

(1).pom.xml

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

参考

@Api()用于类；表示标识这个类是swagger的资源

tags–表示说明

value–也是说明，可以使用tags替代

@ApiOperation() 用于方法；表示一个http请求的操作

value用于方法描述

notes用于提示内容

tags可以重新分组（视情况而用）

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

name–参数名

value–参数说明

required–是否必填

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收

value–表示对象名

description–描述

都可省略

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上

比较简单, 这里不做举例

@ApiImplicitParam() 用于方法
表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

name–参数ming

value–参数说明

dataType–数据类型

paramType–参数类型

example–举例说明

(3).代码

A: swagger配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("代购服务器接口API")
                .version("1.0")
                .build();
    }    
}

B: controller配置：

@Api(description="测试swagger")
@RestController
public class TestHttpController {

    @ApiOperation(value="协议模块",notes="http接口")
    @RequestMapping("/http")
    public String testHttp(){

        return "http";
    }
}

(4).浏览器访问

http://ip:port/swagger-ui.html