5分钟集成实现SpringBoot自动生成API接口文档(上篇)

  |   0 评论   |   浏览

image-20201115233510014

当你问10个开发人员想不想写开发文档,可能有11个人会告诉你,不想写;那有没有方式可以不写接口文档,能自动生成呢?当然是有的,业界比较主流的是使用丝袜哥(swagger);但是个人使用过程中,觉得它对代码的侵入性有点强,虽然减轻了文档撰写的工作量,但是带来了一些编码的负担,同时和整个业务功能耦合的比较严重;

下面推荐一个非侵入的API生成工具apigcc : https://github.com/apigcc/apigcc 使用起来也非常的简单,而且对代码几乎零侵入。

话不多说,代码走着。。。

测试源码

源码https://gitee.com/pengfeilu/apigcc-demo

入门基础教程

开始5分钟的集成示例;

单模块图示

image-20201115215421046

第一步,引入jar
<dependency>
    <groupId>com.github.apiggs</groupId>
    <artifactId>apiggs-maven-plugin</artifactId>
    <version>1.6</version>
    <type>pom</type>
</dependency>
第二步,引入插件
<plugin>
   <groupId>com.github.apiggs</groupId>
   <artifactId>apiggs-maven-plugin</artifactId>
   <version>1.6</version>
   <executions>
      <execution>
         <phase>compile</phase>
         <goals>
            <goal>apiggs</goal>
         </goals>
      </execution>
   </executions>
   <configuration>
      <!-- options in there -->
      <id>index</id>
      <title>订单管理功能API文档</title>
      <production>order</production>
      <out>target/docs</out>
      <dependency>../order/src/main/java</dependency>
      <version>1.0.0</version>
      <description>
         访问:http://127.0.0.1/api/order/[接口名]

         非JSON格式传递的参数,请使用form-data的方式传值

         默认所有接口请求头部(header)中加入如下参数
              timestamp: 请求的当前时间戳,秒
              sign: 进行MD5后的签名

      </description>
   </configuration>
</plugin>

值得注意的部分都在configuration里面

  • production
    输出的目录名称;一般和项目名称保持一致;默认是apiggs
  • out
    输出的路径;这里设置放置在target/docs目录下
  • 工作路径
    源码路径,../order/src/main/java;主要方便于多个模块配置
  • version
    版本号
  • description
    描述信息,这里可以添加项目特殊的附加信息;比如访问地址,特殊的公共参数;传参方式等等
第三步,测试代码

创建一个SpringBoot项目,添加下面的测试代码。

/**
 * 订单管理
 */
@RestController
@RequestMapping("/order")
public class OrderController {

    /**
     * 根据单号获取的订单
     * @param orderNo 订单号
     * @return 订单对象
     */
    @GetMapping("get")
    public OrderInfoVo getOrder(@RequestParam(defaultValue = "2020111111") String orderNo){
        return null;
    }

    /**
     * 创建订单
     * @param orderInfo 订单信息
     * @return 是否添加成功
     */
    @PostMapping("add")
    public Integer add(@RequestBody OrderInfoVo orderInfo){
        return 1;
    }
}
第四步,输出文档
mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs

image-20201114114347039

第五步,页面测试

找到输出的目录;双击index.html,即可得到以下api文档界面

image-20201114114930075

第六步,将其配置到web容器中

上面得到的只是一个静态的页面,本地访问可以,api文档嘛,毕竟不是给自己看的,主要是给团队的其他同事看的,因此,必定要做到别人能通过浏览器访问到

下面就通过Nginx,代理这个静态文件

  • 将生成的目录拷贝到nginx所在服务器的任意目录
    将文件拷贝到: /opt/apiggs/order
    image-20201114120038636

  • 配置nginx

    location /order/
    {
        root   /opt/apiggs/;
        index  index.html index.htm;
    }
    
  • 测试

    访问: http://192.168.1.222/order/index.html

    image-20201114182035121

到此,基础的用法已经介绍完了;是不是说5分钟就5分钟,因为真的简单。

但是实际开发过程并不会是这么简单的需求,也不可能只是这么一个模块,只会更加的复杂;

面对复杂的项目结构,我们该如何处理呢?

实战用法

效果展示

image-20201114183247994

如上图所示测试项目;分了好多个模块;订单、商品、用户或者更多;如果生成文档呢?

难道每一个模块生成一个?然后放到nginx里面,一个个的访问?

http://192.168.1.222/order/index.html

http://192.168.1.222/product/index.html

http://192.168.1.222/users/index.html 这样?显然不是!!!

这样如果涉及到几十个模块,那特么链接就会记疯了,我们希望的是下面这样的效果,用一个主页页面把这些模块装起来,然后再分模块展示出来。

image-20201114183959142

开始配置
多模块图示

image-20201115215550535

获取主页页面

这部分内容比较多,就不占篇幅贴出来了

文件所在地址: https://gitee.com/pengfeilu/apigcc-demo/tree/master/api-doc-docker

image-20201116135624062

每个模块生成文档
cd ./order
mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs
              
cd ../product
mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs
              
cd ../users
mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs

image-20201114185020569

将主页页面和模块api页面放到一起

image-20201114190124394

修改主页页面配置

第一步下载的那个主页页面index.html

image-20201114190230057

  • 第一处,整个项目的名称;页面打开的title

    <title>测试项目后台管理接口API</title>
    
  • 第二处,修改模块信息

    将下面部分配置,按照自己实际的模块情况修改

    image-20201114185333295

通过nginx代理
  • 将文件夹拷贝到nginx服务器
    目录:/opt/apiggs/api/
    或者直接拷贝到nginx的默认路径: /usr/share/nginx/html/

  • 配置nginx

    注意这里只能放置到路径的根目录,如果80端口已经占用;可以配置另外一个端口

    通过端口进行访问

    # 用已经在用的端口配置
    location /
    {
        root   /opt/apiggs/api/;
        index  index.html index.htm;
    }
    
    #或者 新开一个server配置
    server {
        listen       8080;
        server_name  localhost;
    
        location /
        {
            root   /opt/apiggs/api/;
            index  index.html index.htm;
        }
    }
    

    重启nginx

    nginx -t
    nginx -s reload
    
  • 测试

    http://192.168.1.222:8080

    image-20201114192333614

自动部署

上面的几轮操作,我们想要的效果已经达到了,但是全程操作都是手动进行;虽然没让我们去写文档;要是每次都按这么一顿操作;那岂不是要把人折磨疯;

下面就带着大家通过 gitlab + jenkins + docker + apigcc 来搭建一个完全解放双手的api生成方案;由于这一块涉及的东西比较多,所以另外起了一个新的博客来介绍;《5分钟集成实现SpringBoot自动生成API接口文档(下篇)》 : https://lupf.cn/articles/2020/11/15/1605454832274.html



标题:5分钟集成实现SpringBoot自动生成API接口文档(上篇)
作者:码霸霸
地址:https://blog.lupf.cn/articles/2020/11/14/1605361026782.html