Java非侵入式API接口文档工具apigcc用法详解

概述

apigcc是一款非侵入式的API接口文档生成工具，可以帮助Java开发人员快速生成符合RESTful标准的API接口文档，同时支持多种API文档输出格式，包括HTML、Markdown、PDF等格式。

安装

apigcc可以通过npm安装，使用如下命令即可：

npm install apigcc -g

配置

apigcc需要通过配置文件来指定API文档中需要包含的接口信息以及文档输出格式等。可以使用以下命令生成默认配置文件：

apigcc init

默认配置文件为apigcc.yml，该文件的详细配置说明可以参考官方文档。

生成文档

配置文件完成后，就可以开始使用apigcc生成API接口文档了。使用如下命令生成HTML格式的API文档：

apigcc gen -o path/to/output -f html

其中，-o参数指定输出文件夹，-f参数指定输出格式。

示例1 - 使用Swagger注解生成文档

apigcc可以通过解析Java源代码中的Swagger注解来自动生成API接口文档，示例如下：

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/user")
@Api(tags = "用户管理接口")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping("/{id}")
    public User getUserById(@ApiParam(value = "用户ID") @PathVariable Long id) {
        // 处理获取用户信息逻辑
        return user;
    }

    @ApiOperation("创建用户")
    @PostMapping("/")
    public void createUser(@ApiParam(value = "用户信息") @RequestBody User user) {
        // 处理创建用户逻辑
    }
}

配置文件指定如下：

input: src/main/java
output: target/apidocs
language: java
custom:
  - "com.github.apidoc.apigcc.spring.SpringFilter"

使用如下命令生成HTML格式的API文档：

apigcc gen -o target/apidocs -f html

结果如下：

示例2 - 使用YAML文件生成文档

apigcc还支持通过YAML文件自定义API接口文档信息，示例如下：

---
apis:
- path: /api/v1/user/{id}
  method: GET
  summary: 获取用户信息
  parameters:
  - name: id
    description: 用户ID
    required: true
    type: integer
    format: int64
    in: path
  responses:
    "200":
      description: 返回用户信息
      schema:
        $ref: "#/definitions/User"
  tags:
  - User
- path: /api/v1/user/
  method: POST
  summary: 创建用户
  parameters:
  - name: user
    description: 用户信息
    required: true
    type: object
    in: body
    schema:
      $ref: "#/definitions/User"
  responses:
    "201":
      description: 用户创建成功
    "400":
      description: 用户信息不完整或格式不正确
  tags:
  - User
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      age:
        type: integer

配置文件指定如下：

input: src/main/resources
output: target/apidocs
language: markdown
custom:
  - "com.github.apidoc.apigcc.example.spring.BasicSwaggerFilter"

使用如下命令生成Markdown格式的API文档：

apigcc gen -o target/apidocs -f markdown

结果如下：

# User

## 获取用户信息 [/api/v1/user/{id}]

+ Parameters
    + id (integer, path, required) ... 用户ID

+ Response 200 (application/json;charset=UTF-8)

        {
            "id": 1,
            "name": "张三",
            "age": 25
        }

### 获取用户信息 [GET]

    获取用户信息

## 创建用户 [/api/v1/user/]

+ Parameters
    + user (User, body, required) ... 用户信息

+ Request User (application/json;charset=UTF-8)

    {
        "id": 1,
        "name": "张三",
        "age": 25
    }

+ Response 201

    用户创建成功

+ Response 400

    用户信息不完整或格式不正确

### 创建用户 [POST]

    创建用户

小结

以上就是使用apigcc生成API接口文档的详细攻略，包括了安装、配置和生成文档等过程，并提供了两个示例说明如何使用apigcc生成API接口文档。希望对于大家学习apigcc有所帮助。