【Java学习-进阶】-swagger配置与优化

1、Swagger简介

Swagger是一个实现了OpenAPI(OpenAPI Specification)规范的工具集。OpenAPI是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。
官网地址：https://swagger.io/

2、工具集介绍

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger UI： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。
SwaggerEditor： Swagger文件编辑器，可以在线或者本地编辑描述文件，类似于markdown。
Swagger Codegen： 基于OpeanAPI的规范，通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，支持通过jar包，docker，node等方式在本地化执行生成。也可以在Swagger Editor中在线生成。
Swagger Inspector（免费）： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义
SwaggerHub（免费和商业）： 集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

3、Maveny依赖引入

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

4、配置编写

/**
 * swagger API测试配置
 *
 * @author xxx
 */
@Configuration
@EnableSwagger2  //表示swagger表示Swagger的开关，已经启用swagger
public class Swagger2 {

    @Value("${spring.application.name}")
    private String appName;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(true).select()
          .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//监控所有RestController注解的
          .paths(PathSelectors.any()).build();//对跟下所有路径进行监控
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(appName + "项目接口文档")
          .contact(new Contact("xxx", "", "xxx@163.com"))
          .description(appName + "服务API接口文档")
          .license("The Apache License, Version 2.0")
          .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
          .version("1.0")
          .build();
    }
}

5、常用注解配置

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数

6 演示结果

游览器输入：http://localhost:8080/swagger-ui.html

7优化

引入Maven依赖

<dependency>
   	<groupId>com.github.xiaoymin</groupId>
   	<artifactId>swagger-bootstrap-ui</artifactId>
   	<version>1.9.6</version>
</dependency>

游览器输入：http://localhost:8080/doc.html