定义 Swagger 配置类，自定义 API 文档信息

定义 Swagger 配置类，自定义 API 文档信息

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格 的 Web 服务,在实际开发中，常用Swagger-API接口文档自动生成工具，帮助项目自动生 成和维护接口文档。

它具有以下特点：

• 及时性：接口变更后，Api文档同步自动更新

• 规范性：遵守RESTful风格，保证接口的规范性，如接口的地址，请求方式，参数及 响应

​ 格式和错误信息

• 一致性：接口信息一致，不会出现因开发人员拿到的文档版本不一致而导致分歧

• 可测性：直接在接口文档上进行测试，可以在线测试Api接口，方便理解业务

在 SpringBoot 项目中应用 Swagger

1. 在 SpringBoot 项目中应用 Swagger

    <!--   swagger 核心依赖-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!--   swagger ui 依赖-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

2. 开启swagger

   在项目的启动类上加上@EnableSwagger2注解，表示开启Swagger，同时它也支持自 定义UI页面的一些信息。

   

3. 启动项目，访问API在线文档页面

   http://localhost:8080/swagger-ui.html

4. 定义 Swagger 配置类，自定义 API 文档信息

   /**
    *  Swagger配置类
    */
   @Configuration
   public class SwaggerConfig {
       public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.demo";
   
       public static final String VERSION = "1.0.0";
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                   .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("我的第一个项目")   //设置文档的标题
                   .description("*** API 接口文档")   // 设置文档的描述
                   .version(VERSION)   // 设置文档的版本
                   .contact(new Contact("****", "", "***@qq.com"))
                   .termsOfServiceUrl("http://***.***.***")   // 配置服务网站，
                   .build();
       }
   
   }
   

5. 通过注解来完善API文档

   （1）@Api注解： 用来标记当前 Controller 的功能。

​ （2）@ApiOperation注解：用来标记一个方法的作用。

​ (3) @ApiImplicitParam注解：用来描述一个参数，可以配置参数的中文含义，也 可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

​ (4) @ApiModel ：用在实体类上，主要属性有description(描述)、parent(父类)、 subTypes、value、discriminator等；

​ @ApiModelProperty：用在实体类属性上，主要属性有access、accessMode、 allowableValues、allowEmptyValue(是否允许为空)、dataType(数据类型)、example(示 例)、hidden(是否隐藏)、name(名称)、notes、required(是否必需)、value(说明)等。