OpenAPI Specification

Fern | 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:

2 /movies:
3 post:
4 summary: Create a new movie
5 requestBody:
6 required: true
7 content:
8 application/json:
9 schema:
10 $ref: '#/components/schemas/Movie'
11 examples:
12 movieExample:
13 summary: This is an example of a movie
14 value:
15 name: Schindler's List
16 rating: 5.0
17 id: tt0108052

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.

2 examples:
3 MovieExample:
4 summary: Example of a movie object
5 value:
6 name: Shawshank Redemption
7 rating: 5.0
8 id: tt0111161
11 /movies/{movieId}:
12 get:
13 summary: Get movie by ID
14 parameters:
15 - name: movieId
16 in: path
17 required: true
18 schema:
19 type: string
20 responses:
21 '200':
22 description: A movie object
23 content:
24 application/json:
25 schema:
26 $ref: '#/components/schemas/Movie'
27 examples:
28 MovieExample:
29 $ref: '#/components/examples/MovieExample'

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:

1import * as IMDb from "../../..";
4 * @example
5 * {
6 * title: "Shawshank Redemption",
7 * rating: "5.0",
8 * id: "tt0111161"
9 * }
10 */

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.

Example in Fern Docs

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.