OpenAPI接口规范

OpenAPI 是一种用于构建和描述 RESTful API 的工具，本文将为你详细介绍 OpenAPI 接口规范，让你的 API 开发更加标准化。

用 Apifox，节省研发团队的每一分钟

OpenAPI接口规范

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

OpenAPI 接口规范

OpenAPI 是描述 HTTP API 的标准方式。今天来讲讲它的接口规范（OpenAPI 规范 (中文版)）~

OpenAPI 官网

OpenAPI 版本号规范

OpenAPI 的版本号是使用 major.minor.patch 格式来定义的，比如 3.1.2

  • major： 规定大版本
  • minor： 规定小版本
  • patch： 规定小版本中的修补

OpenAPI 格式规范

OpenAPI 可以使用 JSON 或 YAML 的格式，且字段区分大小写：

{
   "sports": [ "ball", "swimming" ]
}

JSON 示例

{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

YAML 示例

title: Sample Pet Store App
summary: A pet store manager.
description: This is a sample server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

OpenAPI 文档结构规范

OpenAPI 文档可以是单个文档，也可以多个文档，由你们团队自行决定。在后一种情况， 需要在 Reference Objects 和 Schema Object 中使用 $ref 关键字。

而文档的命名，建议命名为 openapi.json 或 openapi.yaml。

OpenAPI 数据类型规范

OpenAPI 的数据类型，必须符合 JSON Schema Specification Draft 2020-12 的规范才行

JSON Schema 规范地址：https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1
typeformatcomments
integerint32signed 32 bits
integerint64signed 64 bits (a.k.a long)
numberfloat
numberdouble
stringpasswordA hint to UIs to obscure input.

OpenAPI 富文本格式规范

OpenAPI 的 description 字段是支持 CommonMark markdown 格式的，所以在 OpenAPI 中使用富文本，格式必须符合 CommonMark markdown 格式。

OpenAPI 对象

Info Object

描述 API 的元数据

{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

Contact Object

API 的联系信息

{
  "name": "API Support",
  "url": "https://www.example.com/support",
  "email": "support@example.com"
}

Server Object

API 的服务器对象信息

可以是一个服务器

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

也可以是多个服务器

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

Components Object

API 的可复用组件对象

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

Paths Object

描述 API 的 URL 的对象

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {          
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

Path Item Object

单个路径上可用操作的对象

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

Operation Object

路径上单个 API 操作的对象

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": { 
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"] 
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

External Documentation Object

拓展外部资源

{
  "description": "Find more info here",
  "url": "https://example.com"
}

Parameter Object

参数对象

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

Request Body Object

单个请求 Body 的对象

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example", 
            "externalValue": "https://foo.bar/examples/user-example.json"
          } 
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "https://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "https://foo.bar/examples/user-example.txt" 
        }
      } 
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

Responses Object

API 返回响应的对象

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

Header Object

请求头的对象

{
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

使用 Apifox 管理 OpenAPI API

Apifox 是一款集 API文档、API管理、API测试于一身的超级多功能 API 工具，日常用 Apifox 来管理 OpenAPI 的 API 项目，那是再合适不过了

Apifox 的 API 管理

Apifox 的 API 管理功能很齐全，包括

  • 接口数管理
  • operationID
  • Mock 功能
  • 请求定义、请求示例
  • 响应定义、响应示例
  • 唯一标识
Apifox 的 API 管理

Apifox 的自动化测试

Apifox 的自动化测试也很完善，功能包括

  • 测试用例：可以测试多个接口或接口用例
  • 测试套件：可以测试多个测试用例
  • 可以设置循环数、延迟书、环境、线程数等参数进行运行
  • 支持导出测试报告
  • 支持查看单个接口的测试结果
  • 支持查看测试结果的详细参数
Apifox 的自动化测试

Mock 功能

Apifox 支持 Mock 功能，定义完接口响应之后，通过本地 Mock 功能可得到 Mock 数据

Mock 功能

点击 发送，即可获取 Mock 数据

Mock 数据

导出导入 OpenAPI

Apifox 支持导出导入 OpenAPI，如果你想要进行 API 项目迁移的时候，可以考虑下这个功能，能让你以最低的成本，去进行项目迁移

导入数据
导出数据

关于 Apifox

  • 集成了 API 文档、API 调试、API Mock、API 自动化测试 API 一体化协作平台
  • 拥有更先进的 API 设计/开发/测试工具
  • Apifox = Postman + Swagger + Mock + JMeter

欢迎体验一下，完全免费的哦：在线使用 Apifox

Apifox
OpenAPI API 开发 接口开发 接口定义 API 规范
相关推荐