14个文本转图像AI API
5 个用于记录 Web API 的工具
2024-12-12
了解记录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文档是一本详细阐述如何运用API（无论是REST、gRPC还是GraphQL）的手册。它全面概述了开发人员所需了解的数据结构、函数、参数、返回类型及类等参考信息。
构建API只是成功之路的一半。一个缺乏文档的API会引发产品构建团队间的诸多摩擦。而手动更新文档常因易出错而成为一大难题。若文档未能及时更新，则会令依赖其的人员遭遇挫败。
为什么要记录 API？
记录完备的API具备以下优势：
1. 可维护的 API
API 文档提倡在构建应用程序时采用设计优先的方法。这意味着开发人员在编写任何代码之前都会创建一个 API 规范。这种做法使得API能够更好地适应未来的需求，并且维护起来相对轻松。依据这份规范，团队能够：
- 在开发开始之前确定问题。
- 创建 API 预期工作方式的高级概述。
- 拆分任务的实现。
2. 可预测的 API
文档描述了不同操作的预期返回数据结构。依赖于它的前端应用程序、服务或微服务将“知道”返回的数据结构，从而降低出现问题的几率。 当应用程序的某个部分的类型发生更改时，编译器将通知您并引发应用程序受影响部分的错误或警告，这些部分需要更新才能运行应用程序。
3. 改善协作
文档为其他团队和开发人员在构建应用程序时所依赖的提供了参考。开发人员可以依据文档来了解API的用法、错误信息和结构。优质的文档能够显著提升开发人员在使用API时的体验。
此外，该文档还可用于追踪API实施的进度，明确创建的抽象概念，并促使团队在API的目标上达成共识。
工具
本节将深入介绍几种不同的工具，这些工具旨在协助您和您的团队为Web API打造清晰、详尽的文档。
Swagger
Swagger是一个遵循Open API规范的工具，该规范为基于HTTP的API提供了一种标准化的、与编程语言无关的接口描述方式。
Swagger专用于记录REST API，能够详尽阐述API可执行的操作，包括请求参数、查询参数或请求体，以及响应对象和状态码。此外，该文档还清晰地定义了API在发送或接收数据时所预期的数据结构。通过Swagger生成的文档，用户可以创建API测试用例，自动化执行依赖API的流程，并体验一个交互式的测试环境来验证API的功能。
Swagger 提供的另一个好处是使用 Swagger Codegen 生成客户端 SDK 和服务器存根。
对于不同的编程语言和框架，Swagger提供了相应的实现版本，例如针对NestJS等框架的定制版本。
使用 NestJS 的 Hello world Swagger 示例
首先，从工作目录中的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
Postman 提供了一系列在API开发流程中可运用的工具，包括自动测试、请求组织、模拟以及监控等服务。其中，Postman的API平台特别适用于为REST和GraphQL API创建文档。
实现这一功能的方式是在Postman中创建集合，并将请求归类到不同的文件夹内。为了成功发布集合，用户需要先登录自己的账户。点击发布按钮后，Postman会根据集合内容自动生成文档。
在此示例中，您可以参考一个包含针对基于REST API的Prisma示例的请求的集合。您可以在Postman中导入该集合，并亲自进行试用。
您可以通过使用JSON2Ts等工具，轻松地将JSON格式的响应数据转换为前端应用程序的TypeScript接口，从而在这个工作流程中确保类型安全得到强制执行。
GraphQL
GraphQL是一种强大的API查询语言，它支持声明式的数据获取方式。GraphQL API主要由两个核心组件构成：架构定义和解析器。其中，架构定义了API的行为和特性，而解析器则是实现这些架构定义的函数。
值得一提的是，文档在GraphQL的类型系统中扮演着至关重要的角色。GraphQL的架构本身就具备自文档化的特性，这极大地降低了因手动更新文档而产生的人为错误的风险。GraphQL API会根据其查询定义来构建架构，并自动生成GraphQL Playground或GraphiQL等工具所需的文档。
根据GraphQL的规范，内省系统所提供的每种类型都包含一个描述字段，该字段能够为用户提供有关特定字段或类型的更多详细信息。尽管GraphQL的操作和类型通常都相当直观，但您仍然可以通过为不同的类型和API操作添加注释来提供额外的有用信息。
Hello world GraphQL 示例
从工作目录中的 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
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 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
同话题下的热门内容
