如何基于Spring Boot 2的Rest接口生成OpenApi 3.0且无需侵入应用？

无需集成到Spring Boot 2应用的生成工具 #

• 静态代码扫描工具：无需修改项目代码、无需新增依赖，仅通过本地脚本扫描项目中的Controller源码，可自动识别Spring Web注解（如@GetMapping、@PageableDefault）、入参结构、返回值类型，直接生成符合OpenApi 3.0规范的文档。
• 流量录制生成工具：如果你的接口可在测试/生产环境正常调用，可通过录制接口的请求、响应流量，自动解析参数结构、返回字段、示例值生成OpenApi 3.0文档，全程无需操作项目代码。
• IDE插件：主流Java IDE均支持对应的OpenApi生成插件，选中对应Controller类即可一键生成规范文件，操作全在本地IDE完成，不会侵入项目。

手动编写OpenApi 3.0参考模板 #

以下是适配你提供的分页接口的OpenApi 3.0模板，可直接基于此扩展其他接口：

openapi: 3.0.3
info:
  title: 足球队位置服务接口文档
  version: 1.0.0
paths:
  /page:
    get:
      summary: 分页查询足球队位置列表
      parameters:
        - name: page
          in: query
          description: 页码，默认从0开始
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: 每页数据条数，默认10
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          description: 排序规则，支持传入多个排序字段
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                description: Spring Page分页返回结构
                properties:
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 0
                        name:
                          type: string
                          example: "Westfalen-Stadion"
                        externalId:
                          type: string
                          example: "externalId"
                        locX:
                          type: number
                          format: double
                          example: 6.02749381870403
                        locY:
                          type: number
                          format: double
                          example: 11.4658129805029452
                        locZ:
                          type: number
                          format: double
                          example: 5.962133212312
                  totalElements:
                    type: integer
                    description: 总数据条数
                  totalPages:
                    type: integer
                    description: 总页数
                  size:
                    type: integer
                    description: 当前页设定的条数
                  number:
                    type: integer
                    description: 当前页码
        '501':
          description: 接口未实现

落地实现思路 #

1. 优先选择静态代码扫描工具生成基础OpenApi文档，仅需后续补充接口、字段的业务描述即可，效率最高，完全不侵入现有Spring Boot 2项目。
2. 如果需要自定义程度更高，可直接基于上面提供的模板扩展其他接口，补充错误码、业务说明等信息即可，无需从零编写。
3. 生成或编写完成后，可使用本地OpenApi格式校验工具检查规范合法性，确保文档可正常用于接口测试、网关接入等场景。

内容的提问来源于stack exchange，提问作者Doncarlito87