如何形成规范的接口文档

一、需求

前后端对接时，后端需要提供一个规范的，或者说前端能够看明白的接口文档是一个非常重要的事。那如何使用注解快速、简单的形成接口文档呢。

二、Swagger2切换knife4j的使用

1、在pom.xml中增加knife4j的相关依赖

<!--整合Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

2、在Swagger2Config中增加一个@EnableKnife4j注解，该注解可以开启knife4j的增强功能 

@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {

    @Bean
    public Docket ssoFront() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("接口所在的包路径"))
                .paths(PathSelectors.any())
                .build().groupName("分组名");
    }

    @Bean
    public Docket ssoAdmin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.admin"))
                .paths(PathSelectors.any())
                .build().groupName("sso-admin");
    }

    @Bean
    public Docket member() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.member"))
                .paths(PathSelectors.any())
                .build().groupName("member-service");
    }

    @Bean
    public Docket system() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.system"))
                .paths(PathSelectors.any())
                .build().groupName("system-service");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("某某模块文档")
                .description("用户模块API文档")
                .contact(new Contact("作者", null, null))
                .version("v1")
                .build();
    }

}

3、运行我们的SpringBoot应用，访问API文档地址即可查看：http://localhost:端口号/doc.html

三、功能特点

对比swagger来说

1、 返回结果集支持折叠，方便查看

2、 请求参数有JSON校验功能

3、 knife4j支持导出离线文档，方便发送给别人，支持Markdown格式；直接选择文档管理->离线文档功能，然后选择下载Markdown即可

三、根据不同的请求方式使用不同的注解形成接口文档

一、swagger注解应用

1、在控制层当中，可以在controller上使用注解@Api(tags = "接口服务名")标注这个控制器的功能。

2、在具体接口上可以使用注解@ApiOperation(value = "邮箱模糊匹配查询服务接口",notes = "对邮箱进行模糊匹配")对这个接口进行命名以及对这个接口得到功能进行描述

 二、@ApiOperation与Get请求注解配合使用

1、使用注解@RequestParam(value = "传入邮箱",required = false)，注意name和value不能共存，不然无法生成接口文档。swagger会自动识别这个注解生成对应文档

 Get请求数据类型为：

2、使用 @PathVariable(value = "传入邮箱",required = false)也一样。区别只是请求类型不同一个是query，一个是path

3、不需要@ApiImplicitParam(name = "邮箱模糊匹配查询", value = "likeEmail", required = false)这个注解，否者会出现两个一样的参数。

三、@ApiOperation与Post请求注解配合使用

1、使用@RequestBody注解请求参数实体。实体里面在类上头加入

@ApiModel(value = "某某请求报文",description = "某某请求报文,父类是",parent = 类.class)

2、在属性中加入

@ApiModelProperty(value="某某属性",required = true)

    @ApiOperation("某某请求报文")
    @PostMapping("edit")
    public JsonResult edit(@RequestBody EditDTO dto) {
        return 
    }

swagger会自动扫描实体类里面加了注解的数据形成接口文档

3、post请求数据格式

四、所有返回报文如果带有返回参数的需要明确返回参数

只有带了明确返回报文，且报文里 类名@ApiModel和属性@ApiModelProperty也用了注解，那么返回报文的数据类型也会出现在接口文档中。

 下方还会出现相应示例、

注：注解与请求类型的配合使用可参考下面文章

POST、GET、@RequestBody和@RequestParam区别_Archie_java的博客-CSDN博客