Markdown Editor
打开编辑器

API 设计套件

API 风格指南，REST（OpenAPI 3.2）、事件、GraphQL 与 gRPC 规范，版本与弃用策略，以及参考与开发者文档。

第 1 步

标准规范

  1. API Design Guidelines Template (Company Style Guide)

    完整

    Company API style guide: naming, methods, status codes, RFC 9457 errors, pagination, versioning, security, webhooks, governance

  2. API Versioning and Deprecation Policy Template

    标准

    API lifecycle policy: versioning scheme, compatibility promises, breaking changes, timelines, Deprecation and Sunset headers

    RFC 9745 (Deprecation header), RFC 8594 (Sunset header)
第 2 步

规范说明

  1. REST API Specification Template (OpenAPI 3.2, RFC 9457)

    完整

    HTTP/JSON API contract: auth, conventions, QUERY, streaming, pagination, RFC 9457 errors, endpoints, webhooks, OpenAPI 3.2 skeleton

    OpenAPI 3.1, RFC 9110, RFC 9457

  2. Event-Driven API Specification Template (AsyncAPI 3)

    完整

    Async event contract: brokers, channels, operations, CloudEvents envelope, ordering, delivery, DLQ, schema evolution, AsyncAPI YAML

    AsyncAPI 3.0, CloudEvents 1.0

  3. GraphQL Schema Specification Template

    完整

    GraphQL API spec: types, queries, mutations, subscriptions, connections, nullability, errors, auth, cost limits, federation

    GraphQL specification (September 2025 edition)

  4. gRPC Service Specification Template (Protocol Buffers)

    标准

    gRPC service spec: .proto contract, package versioning, field compatibility, google.rpc errors, deadlines, retries, streaming

    gRPC and Protocol Buffers documentation

  5. Interface Control Document (ICD) Template

    完整

    ICD between two systems – parties, requirements allocation, data element table, protocol sequence, errors, security, timing, change control

第 3 步

编写文档

  1. REST Endpoint Reference Template

    标准

    One REST endpoint: auth, parameter tables, request example, responses per status, RFC 9457 errors, limits, idempotency, paging

    OpenAPI, RFC 9457

  2. API Overview and Getting Started Template

    标准

    API landing page – what it does, base URLs, auth in 3 steps, first request, key resources, errors, limits, next steps

  3. Developer and SDK Guide Template

    完整

    Developer guide – setup, auth, multi-language quick start, errors, pagination, rate limits, webhooks, sandbox, versioning