基于OpenAPI3.0.3规范设计API

什么是OpenAPI？

OpenAPI是一种API描述格式，用来描述REST API，用yaml或json格式编写。换句话说，就可以是swagger编辑器中写的yaml的API文档。

Swagger是一套围绕OpenAPI设计、实现等操作的开源工具。最有名的是Swagger Editor 以及各种语言中Swagger的依赖，可以帮助根据注释等自动生成OpenAPI文档。

参考：About Swagger Specification | Documentation | Swagger

REST API设计规范

参考RESTful API 设计指南 - 阮一峰的网络日志 (ruanyifeng.com)

OpenAPI编写语法(YAML)

下面是我自己的一个OpenAPI3文档示例：

# 文档版本信息
openapi: 3.0.3

# 文档基本信息
info:
  title: Seecoder统一代码服务API
  description: "Seecoder统一代码服务是给Seecoder平台其他组件提供代码仓库托管服务的组件"
  contact: 
    name: claws
    email: jingjiecb@gmail.com
  version: '1.0.0'

# 服务器列表
servers:
  - url: https://seecoder-gitlab-server.seec.seecoder.cn
    description: 校外系统服务地址
  - url: https://seecoder-git-server.internal-paas.seec.seecoder.cn
    description: 校内系统服务地址

# 标签（形成的渲染文档会以这个作为分隔）
tags:
  - name: user
    description: 用户相关接口
  - name: other
    description: 其他

# API具体内容
paths:
  /api/user:
    post:
      summary: 创建Git用户
      description: 创建一个新的Git用户
      operationId: createUser
      requestBody: 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitUserDTO'
      responses: 
        '200':
          description: 添加成功
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  res:
                    $ref: '#/components/schemas/GitUserVO'
  /api/user/changePassword:
    post:
      summary: 修改密码
      description: 修改一个学生的密码
      operationId: changePassword
      requestBody: 
        content:
          applictaion/json:
            schema:
            # 引用已定义的数据格式
              $ref: '#/components/schemas/ChangePasswordDTO'
      responses:
        '200':
          description: 有修改结果返回
          content:
            application/json:
              schema:
                type: object
                properties:
                  res:
                    type: boolean
                    description: 表示是否修改成功
        
# API中调用到的其他组件
components:
# 数据格式定义
  schemas: 
    Password:
      type: string
      format: password
      example: 123456

    GitUserDTO:
      type: object
      properties: 
        userId:
          type: integer
          format: int32
        username:
          type: string
          # 数据格式中也可以嵌套引用其他数据格式
        password:
          $ref: '#/components/schemas/Password'
        email:
          type: string
          format: email
    GitUserVO:
      type: object
      properties:
        userId:
          type: integer
          format: int32
        gitlabUserId:
          type: integer
          format: int32
          example: 111
        namespaceId:
          type: integer
          format: int32
          example: 111
        token:
          type: string
    

    ChangePasswordDTO:
      type: object
      properties: 
        userId:
          type: integer
          format: int32
        password:
          $ref: '#/components/schemas/Password'

更多OpenAPI规范参考：OpenAPI Specification - Version 3.0.3 | Swagger