20-Swagger 接口统一管理工具

简介：创建一个接口统一管理工具，使用简洁明了

Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。

swagger的特征
1. 通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档

2. 提供了UI界面。既展示接口信息，又提供了参数校验，测试功能

3. 形成了文档规范，支持不同的语言4. 提供丰富的组件。

一、添加依赖

添加swagger模块，引入依赖

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

二、添加配置类 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createResApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jingdianjichi"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ape-frame")
                .contact(new Contact("经典鸡翅", "git地址", "123@.com"))
                .version("1.0")
                .description("开箱即用的框架")
                .build();
    }
}

三、启动应用 

localhost:8000/swagger-ui.html#/

四、优化 

将配置转移到配置文件里

4.1 创建实体类 SwaggerInfo

@Component
@ConfigurationProperties(prefix = "swagger")
@Data
public class SwaggerInfo {

    private String basePackage;
    private String title;
    private String concactName;
    private String concactUrl;
    private String concactEmail;
    private String version;
    private String description;

}

 4.2 配置类引入实体   参数动态化

@Autowired
private SwaggerInfo swaggerInfo;

@Bean
public Docket createResApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage(swaggerInfo.getBasePackage()))
            .paths(PathSelectors.any())
            .build();
}

public ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title(swaggerInfo.getTitle())
            .contact(new Contact(swaggerInfo.getConcactName(), swaggerInfo.getConcactUrl(), swaggerInfo.getConcactEmail()))
            .version(swaggerInfo.getVersion())
            .description(swaggerInfo.getDescription())
            .build();
}

4.3 application.yml 输入参数 配置

swagger:
  basePackage: com.jingdianjichi
  title: ape-frame
  concactName: 经典鸡翅
  concactUrl: git地址
  concactemail: 123@.com
  version: 1.0
  description: 开箱即用的框架

5 注解配置 便于接口文档展示对应信息 

5.1 @Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

5.2 @ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

5.3 @ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。  可以作用实体类字段上