中文
devexamples
← Workflows

阅读中文版本

SDK Generation from OpenAPI Workflow

Generate client SDKs from the OpenAPI contract, version them with the API, test them against a mock and the real service, and publish per language.

advanced~150 minapisdkautomation

Objective

Produce consistent client SDKs from the contract so consumers integrate with typed, tested clients.

Environment

  • An OpenAPI contract
  • A generator supporting target languages

Steps

1. Generate clients from the contract rather

Generate clients from the contract rather than hand-writing them.

Expected state: Clients cannot drift from the contract.

2. Version the SDK alongside the API

Version the SDK alongside the API version.

Expected state: Consumers know compatibility.

3. Test generated clients against a mock

Test generated clients against a mock and then the real service.

Expected state: Clients are proven to work.

4. Publish per language with changelogs

Publish per language with changelogs from the API changes.

Expected state: Releases are traceable.

Decision points

Generate or hand-write SDKs?

  • Generate
  • Hand-write for control

Generate for consistency and coverage; hand-write thin wrappers only when ergonomics demand it.

One repo or per language?

  • Per language repos
  • Monorepo

A monorepo simplifies coordinated releases; per-language repos suit different maintainers.

Expected outcome

Published, versioned SDKs generated from the contract and tested against both a mock and the live service.

Verification

Confirm generated SDKs pass contract and integration tests and that their version maps to the API version.

Cleanup

Tag the SDK release and record the contract revision used.

Overview

Produce consistent client SDKs from the contract so consumers integrate with typed, tested clients. Confirm generated SDKs pass contract and integration tests and that their version maps to the API version.

Steps

  1. Generate clients from the contract rather than hand-writing them. Expected state: Clients cannot drift from the contract.
  2. Version the SDK alongside the API version. Expected state: Consumers know compatibility.
  3. Test generated clients against a mock and then the real service. Expected state: Clients are proven to work.
  4. Publish per language with changelogs from the API changes. Expected state: Releases are traceable.
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o sdk/ts
# then run integration tests against staging

Verification

  • Published, versioned SDKs generated from the contract and tested against both a mock and the live service.

Decision points

  • Generate or hand-write SDKs? Options: Generate; Hand-write for control. Recommended: Generate for consistency and coverage; hand-write thin wrappers only when ergonomics demand it.
  • One repo or per language? Options: Per language repos; Monorepo. Recommended: A monorepo simplifies coordinated releases; per-language repos suit different maintainers.