SDKs

orbitdocs sdk generates a client library for your API in up to six languages, from the spec OrbitDocs extracted from your Nest app. Each SDK gets code samples in your API reference. Your own additions to an SDK survive every regeneration.

This section also covers the mock server and spec linting:

Generate your first SDKCopy Anchor Link

import { defineConfig } from '@orbitdocs/next/config';

export default defineConfig({
  site: { title: 'Acme' },
  apis: [{ id: 'travel', source: { nest: { module: 'dist/app.module.js', build: 'nest build' } } }],
  sdks: {
    typescript: { package: '@acme/sdk' },
    python: { package: 'acme_sdk' },
    go: { module: 'github.com/acme/acme-go' },
    java: { groupId: 'com.acme', artifactId: 'acme-sdk', package: 'com.acme.sdk' },
    csharp: { package: 'Acme.Sdk' },
    php: { namespace: 'Acme\\Sdk', package: 'acme/sdk' },
  },
});

npx orbitdocs extract

npx orbitdocs sdk                          # every configured language, every API
npx orbitdocs sdk --lang typescript,python # only these languages
npx orbitdocs sdk --api travel             # only this API

LanguagesCopy Anchor Link

Both generators ship with the OrbitDocs CLI. If Java is missing, the command fails with openapi-generator failed for <lang> (it needs Java 11 or later on PATH).

Settings per languageCopy Anchor Link

out is a folder relative to the docs app. It replaces sdks/<api>/<language>.

Several APIsCopy Anchor Link

Each API gets its own SDK. Without out, they go to sdks/<api>/<language>. With out, write {api} where the API id goes; without {api} and with more than one API, each API gets a subfolder of out (<out>/<api>), so no SDK overwrites another. One API uses out as written.

{api} also works in package names, so each API's SDK has its own name. In Python, Java and Go packages and PHP namespaces a - in the id becomes _.

sdks: {
  typescript: { package: '@acme/{api}-sdk', out: 'packages/{api}-sdk' },
  python: { package: 'acme_{api}' },
},

orbitdocs sdk warns when several APIs would share one package name. The reference's code samples (.orbitdocs/sdk-samples.json) are kept per API, each from that API's SDK.

Keep your own codeCopy Anchor Link

Regeneration rewrites generated code only. Where your code is safe depends on the language.

TypeScriptCopy Anchor Link

sdks/travel/typescript/
├── package.json        written once, then yours
├── tsconfig.json       written once, then yours
├── README.md           written once, then yours
└── src/
    ├── index.ts        written once, then yours (re-exports generated/)
    └── generated/      deleted and rewritten on every run

Add helpers next to src/generated/ and export them from src/index.ts. The package builds with npm run build (tsup) to dist/.

export * from './generated';
export { client } from './generated/client.gen';

// Yours: survives regeneration.
export { withRetry } from './retry';

Python, Go, Java, C# and PHPCopy Anchor Link

OpenAPI Generator writes the whole folder, except the files listed in .openapi-generator-ignore. OrbitDocs creates that file on the first run with:

# Files OrbitDocs never overwrites when it regenerates this SDK.
CHANGELOG.md
custom/**
.github/**
.gitlab-ci.yml
LICENSE

Put your own code in custom/, or add your own paths to the file. OrbitDocs never rewrites it after the first run.

OptionsCopy Anchor Link

orbitdocs sdk flagsCopy Anchor Link

Next stepsCopy Anchor Link