Customize reference generation

To describe interfaces across each SDK language and raw HTTP, Stainless uses a custom file format called SDKJSON. The SDKJSON file contains method signatures, types, request/response examples, and more for your API and each of your SDKs.

An SDKJSON is generated from your OpenAPI spec and your Stainless config.

Stainless Docs allows you to define a custom SDKJSON loader function in your Astro config file. This function overrides the framework’s default behavior of fetching your OpenAPI + Stainless config from the Stainless API and generating SDKJSONs behind the scenes.

The simplest way to take advantage of this API is to use fileSystemSDKJSONLoader which reads an OpenAPI spec and Stainless config from the file system and generates SDKJSON files.

Using local OpenAPI and Stainless config files

Using fileSystemSDKJSONLoader completely sidesteps the Stainless API, meaning you do not need an internet connection or Stainless API key to generate API reference documentation.

astro.config.ts

import { defineConfig } from 'astro/config';
import { stainlessDocs } from '@stainless-api/docs';
import { fileSystemSDKJSONLoader } from '@stainless-api/docs';

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: 'My Docs',
      apiReference: {
        stainlessProject: 'my-docs',
        loadSDKJSONFiles: fileSystemSDKJSONLoader({
          specPath: '<path_to_openapi.json>',
          configFilePath: '<path_to_stainless.yml>',
          languages: ['http', 'typescript', 'python'],
        }),
      },
    }),
  ],
});

Advanced usage

Overriding the SDKJSON generation process

You can also optionally override the generateSDKJSON function to further customize the SDKJSON generation process.

astro.config.ts

import { defineConfig } from 'astro/config';
import { stainlessDocs } from '@stainless-api/docs';
import { fileSystemSDKJSONLoader } from '@stainless-api/docs';

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: 'My Docs',
      apiReference: {
        stainlessProject: 'my-docs',
        loadSDKJSONFiles: fileSystemSDKJSONLoader({
          specPath: '<path_to_openapi.json>',
          configFilePath: '<path_to_stainless.yml>',
          languages: ['http', 'typescript', 'python'],
          generateSDKJSON: async ({ spec, config, stainlessProject, language }) => {
            const result = await myCustomSDKJSONGenerationFunction({
              spec,
              config,
              stainlessProject,
              language,
            });
            return result;
          },
        }),
      },
    }),
  ],
});

Writing you own loader function

You can also write your own loader function to completely control the SDKJSON generation process. This is more involved than using the fileSystemSDKJSONLoader, but gives you ultimate control over from where you load your OpenAPI spec and Stainless config, and how you generate the SDKJSONs for each language.

astro.config.ts

import { defineConfig } from 'astro/config';
import { stainlessDocs } from '@stainless-api/docs';
import { writeFile } from 'node:fs/promises';
import path from 'node:path';

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: 'My Docs',
      apiReference: {
        stainlessProject: 'my-docs',
        loadSDKJSONFiles: async ({ createCodegenDir }) => {
          const spec = await fetch('https://example.com/openapi.json').then((r) => r.text());
          const config = await fetch('https://example.com/stainless.yml').then((r) => r.text());
          const result = await myCustomSDKJSONGenerationFunction({
            spec,
            config,
            language: 'typescript',
          });
          const codegenDir = createCodegenDir();
          const sdkJsonFilePath = path.join(codegenDir.pathname, 'sdk.json');
          await writeFile(sdkJsonFilePath, result);
          return [
            {
              path: sdkJsonFilePath,
              languages: ['typescript'],
            },
          ];
        },
      },
    }),
  ],
});