
云原生 API 網關 APISIX 入門教程
了解記錄Web API的重要性、可用的不同方法以及記錄Web API時可使用的工具。
應用程序編程接口(API)是使應用程序能夠相互通信的橋梁。一個典型的例子是前端應用程序利用GitHub API檢索數據,以獲取項目的星標數量。
Web API(REST、GraphQL、gRPC)可以使用客戶端-服務器模型通過?HTTP?協議從其他 Web API 和前端應用程序(來自 Web 瀏覽器和移動應用程序)發送和接收數據。 這意味著前端應用程序或某個Web API(作為客戶端)會向另一個Web API(作為服務器)發送請求,而服務器則會向客戶端返回數據或錯誤響應。
在客戶端發送請求之前,它需要一系列詳細信息,包括協議、目標URL/IP地址、請求的結構、路由參數和查詢、HTTP方法以及標頭。Web API文檔為開發人員提供了這些必要信息,以便他們能在自己的應用程序中有效地使用API。
本文將探討記錄Web API的重要性、其帶來的好處、可用的記錄工具,以及一些能夠進一步提升Web API開發的輔助工具。
API文檔是一本詳細闡述如何運用API(無論是REST、gRPC還是GraphQL)的手冊。它全面概述了開發人員所需了解的數據結構、函數、參數、返回類型及類等參考信息。
構建API只是成功之路的一半。一個缺乏文檔的API會引發產品構建團隊間的諸多摩擦。而手動更新文檔常因易出錯而成為一大難題。若文檔未能及時更新,則會令依賴其的人員遭遇挫敗。
記錄完備的API具備以下優勢:
API 文檔提倡在構建應用程序時采用設計優先的方法。這意味著開發人員在編寫任何代碼之前都會創建一個 API 規范。這種做法使得API能夠更好地適應未來的需求,并且維護起來相對輕松。依據這份規范,團隊能夠:
文檔描述了不同操作的預期返回數據結構。依賴于它的前端應用程序、服務或微服務將“知道”返回的數據結構,從而降低出現問題的幾率。 當應用程序的某個部分的類型發生更改時,編譯器將通知您并引發應用程序受影響部分的錯誤或警告,這些部分需要更新才能運行應用程序。
文檔為其他團隊和開發人員在構建應用程序時所依賴的提供了參考。開發人員可以依據文檔來了解API的用法、錯誤信息和結構。優質的文檔能夠顯著提升開發人員在使用API時的體驗。
此外,該文檔還可用于追蹤API實施的進度,明確創建的抽象概念,并促使團隊在API的目標上達成共識。
本節將深入介紹幾種不同的工具,這些工具旨在協助您和您的團隊為Web API打造清晰、詳盡的文檔。
Swagger是一個遵循Open API規范的工具,該規范為基于HTTP的API提供了一種標準化的、與編程語言無關的接口描述方式。
Swagger專用于記錄REST API,能夠詳盡闡述API可執行的操作,包括請求參數、查詢參數或請求體,以及響應對象和狀態碼。此外,該文檔還清晰地定義了API在發送或接收數據時所預期的數據結構。通過Swagger生成的文檔,用戶可以創建API測試用例,自動化執行依賴API的流程,并體驗一個交互式的測試環境來驗證API的功能。
Swagger 提供的另一個好處是使用 Swagger Codegen 生成客戶端 SDK 和服務器存根。
對于不同的編程語言和框架,Swagger提供了相應的實現版本,例如針對NestJS等框架的定制版本。
首先,從工作目錄中的prisma-examples存儲庫下載rest-nestjs示例。
curl https://codeload.github.com/prisma/prisma-examples/tar.gz/latest | tar -xz --strip=2 prisma-examples-latest/typescript/rest-nestjs
安裝 npm 依賴項:
cd rest-nestjs
npm install
運行以下命令以創建SQLite數據庫文件,并根據prisma/prisma.schema
中定義的內容創建表。
npx prisma migrate dev --name init
安裝 NestJs 所需的 swagger 依賴項:
npm install @nestjs/swagger swagger-ui-express
更新src/main.ts
以初始化Swagger
// src/main.ts
import { NestFactory } from '@nestjs/core'
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'
import { AppModule } from './app.module'
async function bootstrap() {
const app = await NestFactory.create(AppModule)
const config = new DocumentBuilder()
.setTitle('Prisma Examples')
.setDescription('The prisma-examples REST API definition')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
await app.listen(3000)
}
bootstrap()
使用以下命令啟動 REST API:
npm run dev
當應用程序正在運行時,打開瀏覽器并導航到 http://localhost:3000/api,您應該會看到以下內容:
該模塊利用裝飾器來定義API請求,進而生成Swagger文檔,所需裝飾器來自@nestjs/swagger
。
Postman 提供了一系列在API開發流程中可運用的工具,包括自動測試、請求組織、模擬以及監控等服務。其中,Postman的API平臺特別適用于為REST和GraphQL API創建文檔。
實現這一功能的方式是在Postman中創建集合,并將請求歸類到不同的文件夾內。為了成功發布集合,用戶需要先登錄自己的賬戶。點擊發布按鈕后,Postman會根據集合內容自動生成文檔。
在此示例中,您可以參考一個包含針對基于REST API的Prisma示例的請求的集合。您可以在Postman中導入該集合,并親自進行試用。
您可以通過使用JSON2Ts等工具,輕松地將JSON格式的響應數據轉換為前端應用程序的TypeScript接口,從而在這個工作流程中確保類型安全得到強制執行。
GraphQL是一種強大的API查詢語言,它支持聲明式的數據獲取方式。GraphQL API主要由兩個核心組件構成:架構定義和解析器。其中,架構定義了API的行為和特性,而解析器則是實現這些架構定義的函數。
值得一提的是,文檔在GraphQL的類型系統中扮演著至關重要的角色。GraphQL的架構本身就具備自文檔化的特性,這極大地降低了因手動更新文檔而產生的人為錯誤的風險。GraphQL API會根據其查詢定義來構建架構,并自動生成GraphQL Playground或GraphiQL等工具所需的文檔。
根據GraphQL的規范,內省系統所提供的每種類型都包含一個描述字段,該字段能夠為用戶提供有關特定字段或類型的更多詳細信息。盡管GraphQL的操作和類型通常都相當直觀,但您仍然可以通過為不同的類型和API操作添加注釋來提供額外的有用信息。
從工作目錄中的 prisma-examples 存儲庫下載 graphql-sdl-first 示例:
curl https://codeload.github.com/prisma/prisma-examples/tar.gz/latest | tar -xz --strip=2 prisma-examples-latest/typescript/graphql-sdl-first
安裝 npm 依賴項:
cd graphql-sdl-firstnpm install
運行以下命令以創建SQLite數據庫文件,并根據prisma/prisma.schema
中定義的內容創建相應的表(例如User
和Post
等表)。
npx prisma migrate dev --name init
更新內容以包含以下詳細信息:在src/schema.ts
中定義type Post
。
"""
createdAt and updatedAt fields are updated by the database automatically
"""
type Post {
author: User
content: String
createdAt: DateTime!
id: Int!
published: Boolean!
title: String!
updatedAt: DateTime!
viewCount: Int!
}
使用以下命令啟動 GraphQL API:
npm run dev
當應用程序運行時,打開瀏覽器并導航到 http://localhost:4000 以瀏覽 API。 展開 GraphQL Playground 上的 Docs 部分。生成的架構將在 Post 字段下包含注釋:
Protocol Buffers,簡稱Protobuf,是gRPC框架最常采用的接口定義語言(IDL)。gRPC是一個專注于處理遠程過程調用(RPC)的框架,RPC允許在不同遠程系統上調用函數,實現客戶端-服務器間的通信。
請求消息的具體格式被保存在.proto文件中。這些消息定義由包含鍵值對的字段組成,這些字段用于明確每條消息中數據的類型。
package blog;
service Blog {
rpc Feed(FeedRequest) returns (FeedResponse) {}
}
message Post {
optional int32 id = 1;
optional string createdAt = 2;
optional string updatedAt = 3;
required string title = 4;
optional string content = 5;
optional bool published = 6;
}
message FeedRequest {}
message FeedResponse {
repeated Post feed = 1
}
消息的每個字段都被分配了一個唯一的編號,這些數字在定義消息的二進制格式時起到了關鍵作用。為了向使用C/C++等風格的不同字段提供額外的信息,我們可以添加注釋。
JSON Schema 是一種用于驗證 JSON 數據結構的工具。JSON Schema是一種用于驗證JSON數據結構的工具,它可以與Swagger結合使用,共同定義包含API端點的請求和響應對象的架構。此外,JSON Schema作為一種靈活的工具,還適用于其他場景,例如利用Microsoft的自適應卡片來創作用戶界面等。
架構包含六個稱為關鍵字的主要屬性。 這些關鍵詞包括:
$schema
:用于說明架構所遵循的標準和草案版本。$id
:用于定義架構的唯一URL。title
和description
:這兩個屬性為架構提供了描述性的信息,其中title
是架構的標題,而description
則是對架構的詳細描述。type
:用于約束JSON數據的數據類型。properties
:用于驗證每個對象的值應該符合什么樣的結構或模式。使用feed來自 prisma-examples 的請求 – REST API – 返回以下響應:
{
"posts": [
{
"title": "Join the Prisma Slack",
"content": "https://slack.prisma.io",
"published": true,
"createdAt": "2020-06-30T23:01:18.943Z",
"updatedAt": "2020-06-30T23:01:18.943Z",
"authorId": 1,
}
]
}
根據該示例,您可以使用以下 JSON 架構來驗證您的響應:
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://example.com/object1618650097.json",
"title": "Root",
"type": "object",
"required": [
"posts"
],
"properties": {
"posts": {
"title": "Posts",
"type": "array",
"default": [],
"items":{
"title": "Post",
"type": "object",
"required": ["title", "content", "published", "createdAt", "updatedAt", "authorId", "author"],
"properties": {
"title": {
"title": "title",
"type": "string",
},
"content": {
"title": "content",
"type": "string",
},
"published": {
"title": "published",
"type": "boolean",
},
"createdAt": {
"title": "createdAt",
"type": "string",
},
"updatedAt": {
"title": "updatedAt",
"type": "string",
},
"authorId": {
"title": "authorid",
},
}
}
}
}
}
上述架構并未詳盡地羅列出所有可用于數據驗證的屬性。如需更多詳細信息,請參閱JSON Schema規范。
綜上所述,Web API文檔對于內部及外部團隊而言都很重要,因為它極大地提升了開發人員的體驗。盡管編寫文檔可能會顯得有些乏味,但它卻為團隊帶來了諸多益處,如改進API設計、推動可維護和可預測API的開發進程,以及加強團隊協作等。
原文鏈接:https://www.prisma.io/blog/documenting-apis-mjjpZ7E7NkVP