四虎最新永久免费网址,四虎影视成人精品,日韩高清一区二区

"openapi": "3.1.0",
"info": {
"title": "Llama Store API",
"description": "The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to /user with the following body:\n \n``json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n`

\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to

/token with the following body:\n \n`json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n`\n\nThis will return a token that you can use to authenticate with the API:\n\n`json\n{\n \"access_token\": \"<your new token>\",\n \"token_type\": \"bearer\"\n}\n`\n\n## Use the API token\n\nTo use the API token, add it to the Authorization header of your request:\n\n`\nAuthorization: Bearer <your token>\n``\n\n\n" } }

在代碼中設置時，FastAPI 支持將這些類型的 OpenAPI 值添加到 API 代碼中：

app = FastAPI(

    servers=[{"url": "http://localhost:8000", "description": "Prod"}],

    contact={"name": "liblab", "url": "https://liblab.com"},

    description="The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to /user with the following body:\n    \n``json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\"\n}\n`\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to /token with the following body:\n    \n`json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\",\n}\n`\n\nThis will return a token that you can use to authenticate with the API:\n\n`json\n{\n  \"access_token\": \"<your new token>\",\n  \"token_type\": \"bearer\"\n}\n`\n\n## Use the API token\n\nTo use the API token, add it to the Authorization header of your request:\n\n`\nAuthorization: Bearer <your token>\n``\n\n\n",
    openapi_tags=tags_metadata,
    version="0.0.1",
    redirect_slashes=True,
    title="Llama Store API",
)

注意到描述中使用了 markdown，這在文檔中表現良好。這是為 API 規范添加豐富文檔、教程和最佳實踐的有效方法。這種豐富的文檔可以包含代碼示例、錯誤消息等。

生成的文檔不僅應通過 API 提供，還應托管在公共文檔站點上。

其他文檔

除了在 API 規范中記錄 API 外，還可以在公共文檔站點上添加其他文檔。API 規范文檔將作為參考資料，但還應包括教程、操作指南和最佳實踐文檔。

API 規范文檔可以定義每個端點的作用以及如何調用它，但可能無法描述用戶在典型任務中應采取的正確流程。例如，如果 API 包含長時間運行的任務，則需要記錄如何觸發任務、檢查狀態以及檢索結果，這些操作可能涉及不同的端點。

誰應該編寫 API 文檔？

作為從工程工作轉向開發者關系的人，編寫文檔的挑戰顯而易見。雖然這不是大多數工程師的強項或偏好，但它卻是不可或缺的任務。

理想情況下，文檔應由專門的技術作家編寫，他們會與工程師合作了解 API 的工作原理，并與產品團隊協作理解用戶體驗。這些文檔應反饋給工程師，以便納入 API 規范。

然而，現實中，我們常常需要工程師和產品團隊自己編寫文檔，因為他們對 API 最為熟悉，能夠提供最準確的信息。

理想的做法是采用一個框架來簡化文檔編寫。例如，FastAPI 可以輕松地將文檔嵌入 API 代碼中，并生成 OpenAPI 規范。這樣，可以通過拉取請求審查或在 CI/CD 管道中進行 linting 檢查來確保文檔質量。

作為 API 提供商，確保在流程中包含可靠的文檔至關重要！

API 文檔最佳實踐

用清晰的語言書寫

確保文檔用詞清晰明了。避免使用行話，除非它是必要的技術術語，并提供定義或鏈接到其他文檔。設定最低知識要求，定義讀者的基礎知識，以確保每個文檔的內容都能被理解。例如，假設用戶知道如何調用 API，但需詳細解釋如何進行身份驗證和 JSON 對象的基本概念。

展示，不要講述

展示勝于講述。提供實際的示例能夠更好地幫助理解。例如，展示如何從 API 獲取數據，包括請求和響應的具體示例。支持多種編程語言的代碼示例，以滿足不同用戶的需求，如 C# 和 Java 代碼示例。

添加參考文檔、教程和指南

實現不同類型的文檔，包括：

教程：學習導向
操作指南：任務導向
解釋：理解導向
參考文檔：信息導向

參考文檔和解釋應包含在 API 規范中并托管在公共文檔站點上。教程和操作指南則可以放在公共文檔站點上，并應包括快速入門指南，以激發用戶的興趣并促進快速上手。

添加代碼示例

提供代碼示例有助于用戶快速了解如何調用 API。示例不僅展示了如何進行 API 調用，還能展示最佳實踐，如錯誤處理和分頁處理。

保持最新狀態

保持文檔與 API 功能同步更新是關鍵。將文檔更新納入工程和發布流程中，確保新功能和變更都有對應的文檔。通過 PR 流程或 CI/CD 管道中的文檔檢查，確保文檔的持續維護。如果有技術作家，可協助更新，否則工程師和產品團隊應負責編寫和維護文檔。

使其可訪問

確保文檔對所有用戶可訪問，包括視覺障礙者。使用良好的顏色對比度，提供圖像的 alt 文本，并確保文檔支持屏幕閱讀器。考慮將文檔翻譯成其他語言，以覆蓋不說公司默認語言的用戶。

讓它成為專人的責任

指定專人負責文檔編寫和維護。如果文檔未準備好，應暫停發布或功能標志。沒有專人負責，文檔容易被遺忘，導致過時。因此，確保有明確的責任人，以保證文檔的質量和時效性。

通過良好的 API 文檔讓您的 SDK 變得更好

好的 API 文檔的另一個顯著好處是它可以自動成為 SDK 的文檔。使用工具如 liblab，您可以從 API 規范中提取文檔和示例，自動包含在生成的 SDK 中。例如，API 規范中的以下組件可以用于生成 SDK 文檔：

APITokenRequest:

  properties:

    email:

      type: string

      title: Email

      description: The email address of the user. This must be unique across all users.

    password:

      type: string

      title: Password

      description: The password of the user. This must be at least 8 characters long, and contain at least one letter, one number, and one special character.

通過這種方式，SDK 文檔將直接反映 API 規范的內容，確保一致性，并減少維護工作。