OpenAPI 中的字段

OpenAPI（以前称为 Swagger）是用于构建 API（应用程序编程接口）的规范。它提供了一种定义、记录和使用 RESTful API 的标准方法。 OpenAPI 规范以 YAML 或 JSON 格式编写，包括许多用于定义 API 各个方面的字段。

以下是 OpenAPI 中一些最常用的字段：

1. openapi：指定正在使用的 OpenAPI 规范的版本。
2. info：包含有关 API 的信息，例如标题、描述、版本和联系方式。
3. servers：指定托管 API 的服务器。
4. paths：定义 API 的端点 (URL) 和可用于访问它们的 HTTP 方法（GET、POST、PUT、DELETE 等）。
5. components：包含 API 的可重用元素，例如架构、安全方案和响应。
6. security：指定 API 使用的安全方案。
7. tags：提供用于分组和组织操作和端点的元数据。
8. externalDocs：包含指向与 API 相关的外部文档的链接。

这些只是可在 OpenAPI 规范中使用的字段的几个示例。完整的字段列表可以在官方 OpenAPI 规范文档中找到。

Apigit 如何为填补这些领域做出贡献？

虽然并非 OpenAPI 规范中的所有字段都是严格要求的，但必须包含某些字段以确保规范有效且完整。以下是 OpenAPI 规范中的一些必备字段：

1. openapi：指定正在使用的 OpenAPI 规范的版本。此字段是必需的，并且必须包含在规范的根级别。

2. info：包含有关 API 的信息，例如标题、描述、版本和联系方式。此字段是必需的，并且还必须包含在规范的根级别。

3. paths：定义 API 的端点 (URL) 和可用于访问它们的 HTTP 方法（GET、POST、PUT、DELETE 等）。此字段也是必需的，并且必须包含在规范的根级别。

4. servers：指定托管 API 的服务器。此字段不是严格要求的，但建议包含它以提供有关托管 API 的服务器的信息。

5. components：包含 API 的可重用元素，例如架构、安全方案和响应。此字段不是严格要求的，但建议将其包括在内，以便更好地组织和规范的可重用性。

这些是必须包含在 OpenAPI 规范中以确保其有效和完整的基本字段。其他领域如security,tags， 和externalDocs 根据 API 的需要和规范中要求的详细程度，也可能包括在内。

要将 API 规范添加到您的 Apigit 仪表板，请单击位于左上角的“+”号。输入路径名，例如“test/test.json”，以及其他相关信息，例如“标题”和“版本”。空文件将有助于填写所有这些必填字段。

创建一个空的规范文件

那么您的 json 代码将如下所示。

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

Apigit如何助攻更多？

为了说明Apigit如何辅助填写Form格式的字段，这里举几个例子。 添加Field parameter 在Form

那么您的 json 代码将如下所示。

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

添加Field path 在Form

那么您的 json 代码将如下所示。

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },

要探索更多，您可以尝试填写其他字段Form 并切换视图Form 和Code.