IntelliJ+SpringBoot项目实战（三）---基于源代码直接生成漂亮的接口文档

在SpringBoot中可以集成代码插件自动生成接口文档，而且生成的文档很漂亮，除了接口功能介绍、传入参数、响应参数，还具体类似postman的功能，可调用接口进行测试，另外还可以下单WORD版、.md,html格式的文档。下面我们先看下接口文档的展示效果：

下面是实体类参数说明界面：

下面是文档下载界面：

下载的MD文件：

html界面：

类似PostMan的在线调试界面：

提供JS和TS的调用示例：

在线接口文档生成插件可以帮助我们生成可交付的接口文档，大大节省了项目交付的编写开发文档时间。接下来我介绍下如何在SpringBoot中整合在线接口文档插件。

这个接口文档插件交knife4j,是一个集Swagger2和OpenAPI3为一体的增强解决方案。首先我们在openjweb-cloud的主工程中增加knife4j的依赖、lombok依赖（这个使用@Data注解，在实体类中使用），阿里的fastjson（测试接口返回的用JSON结构不能在文档中生成响应参数的说明）：

<dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>1.2.83</version>
</dependency><!--    lombok    -->
<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.2</version>
</dependency><!--   knife4j     -->
<dependency><groupId>com.github.xiaoymin</groupId><!--<artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.4</version>--><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

然后在openjweb-sys子工程的org.openjweb.config下增加一个Swagger2配置类，代码如下：

@Configuration
//@EnableSwagger2
@EnableSwagger2WebMvc
//@EnableKnife4j
public class Swagger2Config {@Bean(value = "dockerBean")public Docket dockerBean() {//指定使用Swagger2规范Docket docket=new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("OpenJWeb低代码平台开发文档")//描述字段支持Markdown语法.description("# OpenJWeb低代码开发平台WXID: openjweb") //产品简介.termsOfServiceUrl("https://github.com/openjweb/cloud/tree/master")//API服务条款.contact("29803446@qq..com")//联系人.version("1.0")//版本号.build())//分组名称.groupName("OpenJWeb低代码平台")//左上角搜索框---分组名称.select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("org.openjweb")).paths(PathSelectors.any()).build();return docket;}
}

注意每个参数对应首页的显示位置可以看首页的图。这些参数指定了文档标题、项目介绍、服务条款、联系人、版本号等。

接下来创建一个实体类CommUser,因为后面示例接口需要返回一个CommUser类型的返回值，在文档中可自动展示返回值说明，下面在org.openjweb.sys.entity下创建一个CommUser类：

package org.openjweb.sys.entity;import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
public class CommUser {@ApiModelProperty(value ="登录账号",required = true)private String loginId;@ApiModelProperty(value ="用户昵称")private String username;@ApiModelProperty(value ="真实姓名")private String realName;@ApiModelProperty(value ="用户性别：男M 女F")private String userSex;}

注意每个属性都增加@ApiModelProperty注解，这样文档中可以显示相应的参数说明。

然后我们创建一个Controller类或者API类，在org.openjweb.sys.api下建一个接口类：

@RestController
@RequestMapping("/ucenter")
@Api(tags = "admin-用户管理")
public class CommUserApi {@ApiOperation("用户详情")@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名称", paramType = "query"),@ApiImplicitParam(name = "province", value = "所属省份", paramType = "query")})@GetMapping("info")public CommUser getUserInfo(@RequestParam(value = "username")String username, @RequestParam(value = "province")String province){//public CommUser getUserInfo( String username, String province){CommUser user = new CommUser();user.setUserSex("男");user.setUsername(username);user.setRealName("王先生");user.setLoginId("abao");return user;}
}

类头部标注此类的接口说明@Api(tags = "admin-用户管理")，这个在文档展示的时候是一个菜单组，然后方法上也增加注解@ApiOperation("用户详情")，这个描述接口的功能，然后@ApiImplicitParams，是接口参数说明，注意接口参数的命名需要和方法参数的(@RequestParam的命名保持一致。

接下来在openjweb-sys子工程的resource目录下建2个文件，一个是application.yml,存放标准配置，一个application-dev.yml是个性化参数配置，application.yml里：