SpringBoot基础之集成接口文档生成

这是我参与11月更文挑战的第6天，活动详情查看：2021最后一次更文挑战

前言

在平时的多人开发过程中,正确的使用优秀的接口文档,可以减少大量的沟通成本,也可以让前后端更有效率的并行开发,更可以让后来者或者维护者更好更快的上手业务.
使用文档比无文档的项目更容易开发,更容易维护.
使用接口文档生成的接口文档,比第三方维护的文档更方便也更轻松,文档也和代码也更一致.

(一) 文档生成工具swagger

swagger是一个能直接生成接口文档,并能进行接口的是的工具.

(1)引入swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

 <!--   默认样式 访问地址: /swagger-ui.html   -->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>
复制代码

其中springfox-swagger2是swagger的主程序,负责将接口整理成restful形式的数据.
而springfox-swagger-ui是默认的swagger前端界面样式包,默认的访问地址是/swagger-ui.html,
此包可以换成自己喜欢的样式包,比如swagger-ui-layer...

(2)springboot整合swagger

//记得注解EnableSwagger2
@EnableSwagger2
@Configuration
public class MySwagger2Config {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger文档标题")
                .description("swagger描述")
                .version("1.0")
                .build();
    }

     @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zouzdc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

}

复制代码

(3)使用swagger注解 注释代码

在然后,在方法和参数上使用@ApiParam,@ApiImplicitParams,@ApiOperation注解参数和接口

@ApiOperation(value="多个参数的例子", notes="两个参数的swagger例子,入参一个必填另个非必填")
@ApiImplicitParams({
        @ApiImplicitParam(name = "one",value = "姓名" ,required = true),
        @ApiImplicitParam(name = "two",value = "年龄")
})
@GetMapping("/moreParams")
public R moreParams(String one,String two){
    return R.success("one",one,"two",two);
}


@ApiOperation(value="传入一个对象", notes="传入对象并解释字段含义")
@GetMapping("/dto")
public R tdtoime(StudentSimpleDto dto){
    return R.success(dto);
}

复制代码

StudentSimpleDto.java 对象

@Data
public class StudentSimpleDto {

    @ApiParam("id")
    private Long id;

    @ApiParam("姓名")
    private String name;

    @ApiParam("年龄")
    private Integer age;

}
复制代码

(4)使用

启动项目,然后访问/swagger-ui.html,即可看到swagger界面了

(二) 文档生成工具JApiDocs

JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档自动生成工具(也可以有注解)

(1)引入JApiDocs依赖

<dependency>
    <groupId>io.github.yedaxia</groupId>
    <artifactId>japidocs</artifactId>
    <version>1.4.4</version>
</dependency>
复制代码

(2)正常写javaDoc注释

 /**
     * 两个参数的swagger例子,两个参数
     * @param one 第一个参数注释
     * @param two 第二个参数注释
     * @return
     */
    @GetMapping("/moreParams")
    public R moreParams(String one,String two){
        return R.success("one",one,"two",two);
    }
    
    /**
     * 传入一个对象,传入对象并解释字段含义
     * @param StudentSimpleDto 对象参数
     * @return
     */
    @GetMapping("/dto")
    public R tdtoime(StudentSimpleDto dto){
        return R.success(dto);
    }
复制代码

StudentSimpleDto.java

@Data
public class StudentSimpleDto {
    /**
     * id
     */
    private Long id;

    /**
     * 姓名
     */
    private String name;

    /**
     * 年龄
     */
    private Integer age;
}
复制代码

(3)使用

在测试类中运行main方法,生成html离线文档,在本地运行项目时可以直接当方法写在springboot的启动类中

public static void main(String[] args) {
      DocsConfig config = new DocsConfig();
        config.setProjectPath("D:\\workSpace\\idea\\sbtest1"); // root project path
        config.setProjectName("项目名称"); // project name
        config.setApiVersion("V1.0");       // api version
        config.setDocsPath("D:\\workSpace\\idea\\sbtest1\\apidoc"); // api docs target path
        config.setAutoGenerate(Boolean.TRUE);  // auto generate
        Docs.buildHtmlDocs(config); // execute to generate
}
复制代码

其中setProjectPath是项目根目录,setDocsPath是文档的生成目录

(三) swagger和JApiDocs对比

swagger解释基本能用的文档,就必须使用注解,必须侵入正常的业务代码

JApiDocs解释基本能用的文档,使用的是javadoc无需写注解,无需侵入代码,javadoc越规范,文档越清晰,但是使用更多的功能则也需要注解

swagger是直接运行直接生成在线的文档,项目启动即api启动

JApiDocs是基于源码生成的离线文档,需要后端控制生成.

    作者：ZOUZDC
    链接：https://juejin.cn/post/7028963866063306760
    来源：稀土掘金
    著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。
复制代码