OpenAPI 3.0 中文文档

OpenAPI

今天给大家讲一下 OpenAPI 3.0 文档中的一些重要点。

文档地址：https://openapi.apifox.cn/

OpenAPI 对象

OpenAPI 文档是由一个个对象组成的，这些对象包括了：

OpenAPI Object：整个 OpenAPI 文档对象
Info Object：描述文档信息的对象
Servers Object：描述服务端的对象
Components Object：描述组件的对象
Paths Object：描述接口路径的对象
Tag Object：接口分组对象
ExternalDocs Object：拓展文档对象
Security Object：安全性对象

通过这些对象的组成，并且生成一个 JSON 或者 YAML 文件，这就是 OpenAPI 文档。

必不可少的 OpenAPI 对象

一个最基本、最原始的 OpenAPI 对象长这样，这其中包含了三个 OpenAPI 必不可少的对象：

OpenAPI Object
Info Object
Paths Object

openapi: "3.0.2"
info:
  title: openAPI Demo
  version: '1.0'
paths: {}

Info Object

title：标题
description: API 描述
version：版本号
license：许可证信息
contact：联系人信息
terms of service：服务条款

openapi: "3.0.2"
info:
  title: openAPI Demo
  description: "This is an API program for teaching"
  version: '1.1'
  termsOfService: "https://openweathermap.org/terms"
  contact:
    name: "api developer"
    url: "http://myblog.cn"
    email: "youemai@gmail.com"
  license:
    name: "Apache 2.0"
    url: "http://springdoc.org"
paths: {}

可以看到文档中的效果。

Paths Object

tags：用于对 endpoint 进行分组的组名
summary：操作对象的摘要信息，最好限制在 5-10 字以内，主要作为概览展示
description：操作对象的描述信息，尽可能的详细，展示细节信息
operationId：操作对象的唯一 ID
parameters：该端点的请求参数对象，描述如下，（ requestBody 描述不在此列包含系列属）
name：参数名称
in：参数出现的位置，通常是 header，path，query，cookie
description：参数的描述（支持 markdown）
required：必填项
deprecated：是否弃用
allowEmptyValue：允许提交空值
style：参数序列化方式
explode：与数组相关的参数
schema：参数的模型
example：媒体类型的示例
requestBody：请求主体的描述，还可以包含一个指向 components 的 $ref 指针
response：响应主体的描述，通常使用标准的 HTTP 状态码，可以包含指向 components 的 $ref 指针
callbacks：回调对象和回调信息的描述，较为少见，不过多介绍
deprecated：标识该 path 是否被弃用
security：仅用于覆盖全局的安全授权方法
servers：仅用于覆盖全局的服务器访问对象

paths:
  /weather:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:

Parameters Object

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "Call current weather data for one location."
      description: "^_^"
      operationId: CurrentWeatherData
      parameters:
      - name: q
        in: query
        description: "^_^"
        schema:
          type: string

Responses Object

responses:
  200:
    description: Successful response
    content:
      application/json:
        schema:
          title: Sample
          type: object
          properties:
            placeholder:
              type: string
              description: Placeholder description

  404:
    description: Not found response
    content:
      text/plain:
        schema:
          title: Weather not found
          type: string
          example: Not found

可以看到文档中的效果：

Security Object

OpenAPI 支持的四种授权的方式：

API key
HTTP
OAuth 2.0
Open ID Connect

如果使用 API key 的话，需要用到 app_id 这个字段，Security Object包含以下几个字段：

type：授权协议，包含了 apiKey、http、oauth2、openIdConnect
description：描述授权方式
name：秘钥名称
in：秘钥的位置，包含 query、header、cookie

components:
  ...
  securitySchemes:
    app_id:
      type: apiKey
      description: API key to authorize requests.
      name: appid
      in: query

可以在文档中看到此效果：

Tags Object

主要是用来进行接口分组的对象：

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets

tags:
  - name: pets
    description: "Chimelong Animal Happy World"

我们可以看到以下的效果：

ExternalDocs Object

此对象不太常用，主要用来做外部文档的引用。

externalDocs:
  description: externalDocs API Documentation
  url: https://openweathermap.org/api

使用 Apifox 管理 OpenAPI API

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

Apifox 的 API 管理

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

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

Apifox 的自动化测试

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

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

Mock 功能

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

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

导出导入 OpenAPI

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

关于 Apifox

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

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