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.