OpenAPI Specification

How to use examples in OpenAPI

Using examples in OpenAPI shows API consumers what requests and responses look like. They can be provided for request bodies, response bodies, and individual parameters.

Inline examples

Examples can be placed directly within the operation definition under paths. Here’s an example:

1paths:
2 /pet:
3 post:
4 summary: Add a new pet to the store
5 operationId: addPet
6 responses:
7 '200':
8 description: A Pet object
9 content:
10 application/json:
11 schema:
12 $ref: '#/components/schemas/Pet'
13 examples:
14 PetExample:
15 summary: This is an example of a Pet
16 value:
17 name: Markley
18 id: 44

Reusable examples

For more general examples that apply to multiple parts of the API, you can define them under the components/examples section. These can be referenced elsewhere in the documentation.

1components:
2 examples:
3 PetExample:
4 summary: Example of a Pet object
5 value:
6 name: Markley
7 id: 44
8
9paths:
10 /pet:
11 post:
12 summary: Add a new pet to the store
13 operationId: addPet
14 responses:
15 '200':
16 description: Successful operation
17 content:
18 application/json:
19 schema:
20 $ref: '#/components/schemas/Pet'
21 examples:
22 PetExample:
23 $ref: '#/components/examples/PetExample'

How Examples are used in Fern SDKs

Fern SDKs use examples from your OpenAPI document to generate comments that show up in your IDE. For example, in a Node.js SDK:

resources/pets/types/Pet.ts
1import * as Petstore from "../../..";
2
3/**
4 * @example
5 * {
6 * name: "Markley",
7 * id: "44"
8 * }
9 */

Here’s an example in GitHub from Flatfile’s Node.js SDK.

How Examples are used in Fern Docs

In the request and response code snippets, you’ll see the example values used.

Screenshot of an example used in response code in Fern Docs API reference

If you generate SDKs with Fern, the code examples for each language will also be populated with the example values. Check out Flatfile’s Docs to see this in action. Change the language toggle to see the examples in different languages.