API Document Auto Generator

Swagger

生态

在这里插入图片描述

接入Swagger

# 添加依赖
  <swagger.version>2.9.2</swagger.version>

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${swagger.version}</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>${swagger.version}</version>
  </dependency>
        
# 配置参数

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled:true}")
    private boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {

        /**
         * basePackage填你要生成的接口的包
         * 不想暴露的接口可以在该API上加注解@ApiIgnore
         */
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnabled)
                .apiInfo(apiInfo())
                // 禁用默认的response
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 信息
     *
     * @return
     */
    private ApiInfo apiInfo() {

        String desc = PrintUtil.format("生成时间：{}", new Date());
        return new ApiInfoBuilder().title("[demo] Service Api Documentation")
                .description(desc).version("1.1").build();
    }
}

参数配置详解：
https://springfox.github.io/springfox/docs/current/#quick-start-guides

启动项目
访问 http://{ip}:{port}/swagger-ui.html 预览界面

在这里插入图片描述

注解
常用注解自己上网搜吧

禁用默认接口返回状态
是否使用默认的接口返回状态
code 201
code 401
code 403
code 404

配置中已给出
useDefaultResponseMessages(false)

禁用Swagger
生产环境禁用swagger
通过配置环境变量 swagger.enabled 在参数配置类中决定是否启动swagger
.enable(swaggerEnabled)

接口测试
点击“Try it out ”，可进行接口测试

利弊分析

优点
接入简单
功能丰富
接口分类
mock测试
缺点
界面不够直观
不支持多项目
一定的注释成本

界面改进

一位前端牛人写的 swagger-ui-layer ，重新排了下版，好看多了
项目已开源
Online demo
http://suldemo.tianox.com/docs.html

# 添加依赖
   <dependency>
       <groupId>com.github.caspar-chen</groupId>
       <artifactId>swagger-ui-layer</artifactId>
       <version>1.1.1</version>
   </dependency>

启动项目，访问 http://{ip}:{port}/docs.html 预览界面
在这里插入图片描述

接口测试
点击“Debug”，可进行接口测试

优缺点分析

优点

简单直观
交互友好
接口测试

缺点

需添加额外注解
无历史版本维护
文档生成要依赖于接口对象定义完成

改造建议
接口搜索
分组过滤
多项目支持
历史版本存储

Java Doc

查看帮助

# 查看帮助命令
javadoc -help

牛刀小试

生成接口文档
javadoc -d /Users/yuan/Desktop/company/doc -sourcepath /Users/yuan/try/demo/src/main/java/com/example/demo/**/*.java -subpackages /Users/yuan/try/demo/src/main/java/com/example/demo/
查看文档
预览界面

优缺点分析

优点

注释即文档
规范代码编写（参照学习 jdk 源码）
类信息详尽
目录层次分明
支持导出

缺点

接口信息不直观
关注点不突出
不支持多项目
不支持mock测试
文档生成要依赖于开发工作的完成

Furthermore

在线编辑
接口搜索
多项目集成
多分支切换
历史版本维护

Reference

https://blog.csdn.net/tuposky/article/details/77965139
https://www.oschina.net/p/swagger-ui-layer