接口定义语言 (Interface Definition Language)

大禹安全 REST API 必须遵循 OpenAPI 规范，我们使用 OpenAPI 描述文件描述整个 API，文件统一采用 YAML 格式定义。

推荐使用代码生成工具生成 API 代码。

以下是描述文件样例 (此描述文件由 API 管理工具导出)：

openapi: 3.0.0
info:
  title: 用户模块 API 文档
  description: 包含用户、角色、资源接口定义及相关说明。
  version: 1.0.0
servers:
  - url: http://api.example.com/v1
    description: v1 版本请求地址
paths:
  /users:
    get:
      tags:
      - User
      summary: 获取用户列表
      operationId: listUser
      responses:
        200:
          description: 返回用户对象集合
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserVo'
    post:
      tags:
      - User
      summary: 添加用户
      operationId: createUser
      parameters:
      - name: user
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/UserAddParam'
      description: ""
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultVo'
  /users/{userId}:
    put:
      tags:
      - User
      summary: 修改用户
      description: ""
      operationId: modifyUser
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
      - name: user
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/UserVo'
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultVo'
    delete:
      tags:
      - User
      summary: 删除用户
      operationId: deleteUser
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultVo'

字段含义

字段名	类型	描述
openapi	string	必选参数，定义语义版本号
info	info Object	必选参数，提供关于 API 的元数据。工具可以根据需要使用元数据。
servers	server Object	可选参数，提供到目标服务器的连接信息。如果没有或是空数组，则默认值将是 url 值为 / 的服务器对象。
paths	paths Object	必选参数，API 访问地址及动作类型。

Info 对象

字段名	类型	描述
title	string	必选参数，文档标题
description	string	文档描述
version	string	必选参数，文档版本

Paths 对象

定义各个的端点和操作的相对路径。这里指定的路径会和 Server 对象 内指定的 URL 地址组成完整的 URL 地址，路径可以为空。

字段名	类型	描述
/	path Object	到各个端点的相对路径，路径必须以/打头

Path 对象

字段名	类型	描述
get	Operation Object	定义一个 Get 请求
put	Operation Object	定义一个 Put 请求
post	Operation Object	定义一个 Post 请求
delete	Operation Object	定义一个 Delete 请求

Operation 对象

字段名	类型	描述
tags	string	定义接口所属组
summary	string	接口概要
description	string	接口描述
operationId	string	定义接口方法名
parameters	Parameter Object	定义接口接受参数
responses	Responses Object	必选参数，定义接口返回响应体

Parameter 对象

字段名	类型	描述
in	string	参数获取位置，例如：path、query、header、cookie
type	string	参数类型，参考数据类型

Responses 对象

字段名	类型	描述
HTTP 状态码	Response 对象	描述状态码的响应