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:

1paths:
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.

1components:
2  examples:
3    MovieExample:
4      summary: Example of a movie object
5      value:
6        name: Shawshank Redemption
7        rating: 5.0
8        id: tt0111161
9
10paths:
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:

resources/movies/types/Movie.ts
1import * as IMDb from "../../..";
2
3/**
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.

Built with