Java 神技：破解经纬度两点距离的终极密码-CFANZ编程社区

在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里：