跳到导航

什么是 API 定义?

以 Markdown 格式查看

API 定义是对你的 API 结构的机器可读规范,包括端点请求和响应模式以及身份验证要求。API 定义能够自动生成这些制品,无需手动保持 SDK 和文档与 API 变更的同步。

Fern 集成了多种 API 定义格式:

原名为 Swagger,OpenAPI 是最流行的 API 定义格式。 OpenAPI 可用于记录 RESTful API,并在 YAML 或 JSON 文件中定义。

查看 Petstore API 的 OpenAPI 规范示例这里

openapi: 3.0.2
tags:
- name: pet
description: Everything about your Pets
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
description: Add a new pet to the store
operationId: addPet
requestBody:
description: Create a new pet in the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
responses:
'200':
description: Successful operation
content:
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/json:
schema:
$ref: '#/components/schemas/Pet'
'405':
description: Invalid input
components:
schemas:
Pet:
required:
- name
- photoUrls
properties:
id:
type: integer
format: int64
example: 10
name:
type: string
example: doggie
category:
$ref: '#/components/schemas/Category'
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
xml:
name: tag
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
xml:
name: pet
type: object

AsyncAPI 是用于定义事件驱动 API 的规范。它用于记录使用 WebSockets、MQTT 和其他消息传递协议的 API。

查看下面聊天应用程序的 AsyncAPI 规范示例:

asyncapi: 2.0.0
info:
title: Chat server
version: 1.0.0
servers:
Production:
url: chat.com
protocol: ws
channels:
"/application":
bindings:
ws:
query:
type: object
properties:
apiKey:
type: string
description: The API key for the client
minimum: 1
bindingVersion: 0.1.0
subscribe:
operationId: sendMessage
message:
$ref: '#/components/messages/SendMessage'
publish:
operationId: receiveMessage
message:
$ref: '#/components/messages/ReceiveMessage'
components:
messages:
SendMessage:
payload:
message: string
ReceiveMessage:
payload:
message: string
from:
type: string
description: The userId for the sender of the message

OpenRPC 是用于描述 JSON-RPC 2.0 API 的规范。它为 JSON-RPC 生态系统提供交互式文档和代码生成工具。

查看下面加密钱包服务的 OpenRPC 规范示例:

# yaml-language-server: $schema=https://meta.open-rpc.org/
$schema: https://meta.open-rpc.org/
openrpc: 1.2.4
info:
title: Basic Wallet API JSON-RPC Specification
description: A simple JSON-RPC API for querying wallet balances.
version: 0.0.1
servers:
- url: https://wallet.example.com/json-rpc
name: Mainnet
methods:
- name: getBalance
description: Get the balance of a wallet address.
params:
- name: address
required: true
description: The wallet address to query.
schema:
type: string
result:
name: balance
description: The balance of the wallet address.
schema:
type: number
examples:
- name: getBalance example
params:
- name: address
value: "0x1234567890abcdef1234567890abcdef12345678"
result:
name: balance
value: 42.5

gRPC 是由 Google 开发的现代开源 RPC 框架。它使用 Protocol Buffers 作为接口定义语言,支持多种编程语言和高效的二进制序列化。

gRPC API 使用 Protocol Buffer (.proto) 文件定义,这些文件指定服务和消息类型。查看下面的 gRPC 服务定义示例:

syntax = "proto3";
package petstore;
// The pet store service definition
service PetStoreService {
// Get a pet by ID
rpc GetPet(GetPetRequest) returns (Pet);
// Add a new pet to the store
rpc AddPet(AddPetRequest) returns (Pet);
// List all pets with optional filtering
rpc ListPets(ListPetsRequest) returns (ListPetsResponse);
}
// Request message for getting a pet
message GetPetRequest {
int64 pet_id = 1;
}
// Request message for adding a pet
message AddPetRequest {
string name = 1;
string category = 2;
repeated string photo_urls = 3;
PetStatus status = 4;
}
// Request message for listing pets
message ListPetsRequest {
int32 page_size = 1;
string page_token = 2;
PetStatus status = 3;
}
// Response message for listing pets
message ListPetsResponse {
repeated Pet pets = 1;
string next_page_token = 2;
}
// Pet message definition
message Pet {
int64 id = 1;
string name = 2;
string category = 3;
repeated string photo_urls = 4;
PetStatus status = 5;
}
// Pet status enumeration
enum PetStatus {
PET_STATUS_UNSPECIFIED = 0;
PET_STATUS_AVAILABLE = 1;
PET_STATUS_PENDING = 2;
PET_STATUS_SOLD = 3;
}

为什么要创建 API 定义?

一旦你有了 API 定义,Fern 就会将其作为输入来生成制品,如 SDK 和 API 参考文档。每次更新 API 定义时,你都可以重新生成这些制品,确保它们始终保持最新状态。