API 定义是对你的 API 结构的机器可读规范,包括端点、请求和响应模式以及身份验证要求。API 定义能够自动生成这些制品,无需手动保持 SDK 和文档与 API 变更的同步。
Fern 集成了多种 API 定义格式:
OpenAPI (REST 和 Webhook API)
原名为 Swagger,OpenAPI 是最流行的 API 定义格式。 OpenAPI 可用于记录 RESTful API,并在 YAML 或 JSON 文件中定义。
查看 Petstore API 的 OpenAPI 规范示例这里
openapi: 3.0.2tags:- name: petdescription: Everything about your Petspaths:/pet:post:tags:- petsummary: Add a new pet to the storedescription: Add a new pet to the storeoperationId: addPetrequestBody:description: Create a new pet in the storerequired: truecontent: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 operationcontent:application/xml:schema:$ref: '#/components/schemas/Pet'application/json:schema:$ref: '#/components/schemas/Pet''405':description: Invalid inputcomponents:schemas:Pet:required:- name- photoUrlsproperties:id:type: integerformat: int64example: 10name:type: stringexample: doggiecategory:$ref: '#/components/schemas/Category'photoUrls:type: arrayxml:wrapped: trueitems:type: stringxml:name: photoUrltags:type: arrayxml:wrapped: trueitems:$ref: '#/components/schemas/Tag'xml:name: tagstatus:type: stringdescription: pet status in the storeenum:- available- pending- soldxml:name: pettype: object
AsyncAPI (WebSocket API)
AsyncAPI 是用于定义事件驱动 API 的规范。它用于记录使用 WebSockets、MQTT 和其他消息传递协议的 API。
查看下面聊天应用程序的 AsyncAPI 规范示例:
asyncapi: 2.0.0info:title: Chat serverversion: 1.0.0servers:Production:url: chat.comprotocol: wschannels:"/application":bindings:ws:query:type: objectproperties:apiKey:type: stringdescription: The API key for the clientminimum: 1bindingVersion: 0.1.0subscribe:operationId: sendMessagemessage:$ref: '#/components/messages/SendMessage'publish:operationId: receiveMessagemessage:$ref: '#/components/messages/ReceiveMessage'components:messages:SendMessage:payload:message: stringReceiveMessage:payload:message: stringfrom:type: stringdescription: The userId for the sender of the message
OpenRPC (JSON-RPC API)
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.4info:title: Basic Wallet API JSON-RPC Specificationdescription: A simple JSON-RPC API for querying wallet balances.version: 0.0.1servers:- url: https://wallet.example.com/json-rpcname: Mainnetmethods:- name: getBalancedescription: Get the balance of a wallet address.params:- name: addressrequired: truedescription: The wallet address to query.schema:type: stringresult:name: balancedescription: The balance of the wallet address.schema:type: numberexamples:- name: getBalance exampleparams:- name: addressvalue: "0x1234567890abcdef1234567890abcdef12345678"result:name: balancevalue: 42.5
gRPC (RPC API)
gRPC 是由 Google 开发的现代开源 RPC 框架。它使用 Protocol Buffers 作为接口定义语言,支持多种编程语言和高效的二进制序列化。
gRPC API 使用 Protocol Buffer (.proto) 文件定义,这些文件指定服务和消息类型。查看下面的 gRPC 服务定义示例:
syntax = "proto3";package petstore;// The pet store service definitionservice PetStoreService {// Get a pet by IDrpc GetPet(GetPetRequest) returns (Pet);// Add a new pet to the storerpc AddPet(AddPetRequest) returns (Pet);// List all pets with optional filteringrpc ListPets(ListPetsRequest) returns (ListPetsResponse);}// Request message for getting a petmessage GetPetRequest {int64 pet_id = 1;}// Request message for adding a petmessage AddPetRequest {string name = 1;string category = 2;repeated string photo_urls = 3;PetStatus status = 4;}// Request message for listing petsmessage ListPetsRequest {int32 page_size = 1;string page_token = 2;PetStatus status = 3;}// Response message for listing petsmessage ListPetsResponse {repeated Pet pets = 1;string next_page_token = 2;}// Pet message definitionmessage Pet {int64 id = 1;string name = 2;string category = 3;repeated string photo_urls = 4;PetStatus status = 5;}// Pet status enumerationenum PetStatus {PET_STATUS_UNSPECIFIED = 0;PET_STATUS_AVAILABLE = 1;PET_STATUS_PENDING = 2;PET_STATUS_SOLD = 3;}
为什么要创建 API 定义?
一旦你有了 API 定义,Fern 就会将其作为输入来生成制品,如 SDK 和 API 参考文档。每次更新 API 定义时,你都可以重新生成这些制品,确保它们始终保持最新状态。