What is the code samples extension?
Many API documentation providers provide code snippets in multiple languages to help developers understand how to use the API. However, these snippets may not correspond to a usage snippet from an existing SDK provided by the API, which reduces the value of the API documentation and can lead to inconsistent integrations, depending on whether a user discovers the API docs or the SDK first.
The x-codeSamples
(previously called x-code-samples
) extension is a widely accepted spec extension that enables the addition of custom code samples in one or more languages to operation IDs in your OpenAPI specification.
When custom code samples are added using the code samples extension, documentation providers will render the usage snippet in the right-hand panel of the documentation page:
Anatomy of the extension
Field Name | Type | Description | Required |
---|---|---|---|
lang | string | The language of the code snippet. Can be one from this list (opens in a new tab). | Yes |
label | string | Code sample label, for example, Node or Python3 . The lang value is used by default. | No |
source | string | The code sample source code. In this case, the SDK usage snippet. | Yes |
Documentation providers that support x-codeSamples
include but are not limited to:
- Mintlify
- Readme
- Redocly
- Stoplight
Example usage
Here is a basic example of using the x-codeSamples
extension with a curl
snippet.
openapi: "3.0.3"info: ...tags: [...]paths: /example: get: summary: Example summary description: Example description operationId: examplePath responses: [...] parameters: [...] x-codeSamples: - lang: "cURL" label: "CLI" source: | curl --request POST \ --url 'https://data.apiexample.com/api/example/batch_query/json?format=json' \ --header 'content-type: application/octet-stream: ' \ --data '{}'
Now let's extend this to a more complex example: a TypeScript SDK for an LLM chat API.
openapi: "3.0.3"info: ...tags: [...]paths: /chat_sessions/chat_results: post: summary: Create Chat Session operationId: create tags: [chat_session] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateChatSession" required: true x-codeSamples: - lang: "typescript" label: "create_chat_session" source: | import { ChatSDK } from "@llm/chat-sdk"; async function run() { const sdk = new ChatSDK({ apiKey: "<API_KEY>", }); const res = await sdk.chatSession.create({ integrationId: "<interagtion_id>", chatSession: { messages: [ { role: "user", content: "How do I get started?", }, ], }, stream: true, }); /* Example of handling a streamed response */ if (res.chatResultStream == null) { throw new Error("failed to create stream: received null value"); } let chatSessionId: string | undefined | null = undefined; for await (const event of res.chatResultStream) { if (event.event == "message_chunk") { console.log("Partial message: " + event.data.contentChunk); chatSessionId = event.data.chatSessionId; } if (event.event == "records_cited") { console.log("Citations: ", JSON.stringify(event.data.citations, null, 2)); } } } run();
Multiple code samples can be added to a single operationId
to support examples in any number of languages by adding multiple keys under the x-codeSamples
extension.
openapi: "3.0.3"info: ...tags: [...]paths: /chat: get: summary: Example summary description: Example description operationId: examplePath responses: [...] parameters: [...] x-codeSamples: - lang: "typescript" label: "chat_ts" source: | ..... ..... - lang: "python" label: "chat_python" source: | ..... .....
Generating code samples
To generate SDK code samples for your OpenAPI document, run the following command:
speakeasy generate codeSamples -s {{your-spec.yaml}} --langs {{lang1}},{{lang2}} --out code-samples-overlay.yaml
This command creates an overlay with code samples for every operationId
in your OpenAPI document.
To apply the overlay to your specification, run:
speakeasy overlay apply -o code-samples-overlay.yaml -s {{your-spec.yaml}} -o {{output-spec.yaml}}
The final output spec will include codeSamples
inline.
Adding code sample generation to your workflow
To include codeSamples
overlay generation in your Speakeasy workflow, add the following to your .speakeasy/workflow.yaml
for any target
you have configured:
If you want the overlay to be automatically applied on the source, create another workflow entry using speakeasy configure
as follows:
Then add the overlay created by Speakeasy to inject code snippets into your spec:
Finally, provide the name and path for your output OpenAPI spec. This will be the final spec used by Mintlify.