# 接口文档

# 概念

在前后端分离的项目中，开发过程中前后端工程师需要有一个统一的文件进行沟通交流开发，共同定义接口，这个定义接口的文档就是接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。它还有一个作用就是在项目维护中或者项目人员更迭的时候，方便后期人员查看、维护。

# 使用说明

在controller的方法上按照规定的格式使用API注解就可以自动生成接口文档。

# 注解说明

@Api 用在类上，该注解将一个Controller（Class）标注为一个资源（API）
@ApiOperation 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。
@ApiImplicitParams 用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。
@ApiImplicitParam 对API的单一参数进行注解。
@ApiParam 增加对参数的元信息说明。
@ApiResponses 注解@ApiResponse的包装类，数组结构。
@ApiResponse 描述一个操作可能的返回结果。

Model注解

@ApiModel 描述一个Model的信息
@ApiModelProperty 描述一个model的属性

下面将对每一个注解进行详细介绍：

# @Api

用在类上，该注解将一个Controller（Class）标注为一个资源（API），平台只会扫描解析具有@Api注解的类。该注解包含以下几个重要属性

tags API分组标签。具有相同标签的API将会被归并在一组内展示。
value 如果tags没有定义，value将作为Api的tags使用
description API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用

# @ApiOperation

在指定的（路由）路径上，对一个操作或HTTP方法进行描述。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

value 对操作的简单说明，长度为120个字母，60个汉字。
notes 对操作的详细说明。
httpMethod HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。

# @ApiImplicitParams

用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。

# @ApiImplicitParam

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：

name 参数名称
value 参数的简短描述
required 是否为必传参数
dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。

# @ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有

required 是否为必传参数，默认为false
value 参数简短说明

# @ApiResponses

注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。

# @ApiResponse

描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。注意：这个注解必须被包含在@ApiResponses注解中。

code HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
message 更加易于理解的文本消息
response 返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。
responseContainer 如果返回类型为容器类型，可以设置相应的值。有效值为 "List", "Set" or "Map"，其他任何无效的值都会被忽略。

Model注解

对于Model的注解，提供了两个：@ApiModel及@ApiModelProperty，分别用以描述Model及Model内的属性。

# @ApiModel

描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）提供对 model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

value model的别名，默认为类名
description model的详细描述

# @ApiModelProperty

描述一个model的属性对model属性的注解，主要的属性值有：

value 属性简短描述
example 属性的示例值
required 是否为必须值

# 注解示例

Api 示例：

@Api(tags = "员工信息")
@RestController
@RequestMapping("/user/staff")
public class StaffController extends BaseController<Staff> {

    /**
     * 分页查询
     *
     * @param staff
     * @return
     */
    @ApiOperation(value = "手写分页查询员工列表")
    @GetMapping("/selectPageStaff")
    public BaseResponse<IPage<Staff>> selectPageStaff(Staff staff) {
        return BaseResponse.success(staffService.selectPageStaff(staff));
    }

    @ApiOperation(value = "测试-手写分页查询员工列表")
    @PostMapping("/selectPageStaff/{name}")
    public BaseResponse<IPage<Staff>> selectPageStaff(@PathVariable @ApiParam("名称") String name, String phone, @RequestBody Staff staff) {
        staff.setName(name);
        staff.setPhone(phone);
        return BaseResponse.success(staffService.selectPageStaff(staff));
    }
}

ApiModel 示例

/**
 * <p>
 * 员工信息表
 * </p>
 *
 * @author 代码生成器
 * @since 2022-02-19
 */
@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@ApiModel(value="Staff对象", description="员工信息表")
@TableName(value = "staff", autoResultMap = true)
public class Staff extends BaseEntity {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "姓名")
    @TableField(value = "name",typeHandler = DataBaseEncryptTypeHandler.class)
    private String name;

    @ApiModelProperty(value = "性别")
    @TableField("gender")
    private String gender;

    @ApiModelProperty(value = "年龄")
    @TableField("age")
    private Integer age;

    @ApiModelProperty(value = "邮箱")
    @TableField("email")
    private String email;

    @ApiModelProperty(value = "手机号")
    @TableField(value = "phone",typeHandler = DataBaseEncryptTypeHandler.class)
    private String phone;

    @ApiModelProperty(value = "部门id")
    @TableField("org_id")
    private String orgId;

    @ApiModelProperty(value = "描述")
    @TableField("description")
    private String description;

    @ApiModelProperty(value = "租户id")
    @TableField("tenant_id")
    private String tenantId;

    @TableField("is_deleted")
    private Integer isDeleted;


}

# 自定义配置类

各模块需要在自己的模块中配置自己的swagger配置路径,将com.mediway.hos.app.core.controller.excel替换成自己controller层的扫描路径即可

@Configuration
public class ExcelSwaggerConfig {
    @Bean
    public Docket excelApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mediway.hos.app.core.controller.excel"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().groupName("excel导入导出")
                .apiInfo(metaData());
    }

    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                .title("HOS消息平台接口文档")
                .version("1.0.0")
                .build();
    }

}