For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Book a demoLog inStart for free
  • Overview
    • What is an API definition?
    • Project structure
      • Overview
      • Overlays
      • Overrides
      • Authentication
      • Servers
      • Sync your specification
      • generators.yml reference
Checking status...
SOC2Soc 2 Type II
© 2026 Fern • Birch Solutions, Inc., a Postman company

Documentation

SDKsDocsAsk FernCLI Reference

API Definitions

OpenAPIAsyncAPIOpenRPCgRPC

Resources

BlogSupportPricing

Company

Brand KitPrivacy PolicyTerms of Service
LogoLogo
Book a demoLog inStart for free
On this page
  • Best practices
  • Set up your fern folder
OpenAPI

What is an OpenAPI specification?

||View as Markdown|
Was this page helpful?
Edit this page
Previous

Project structure

Next

Overlays

The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification is written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes. Fern is compatible with the latest OAS release, which is currently v3.1.1.

Below is an example of an OpenAPI file:

openapi.yml
1openapi: 3.0.2
2info:
3  title: Petstore - OpenAPI 3.0
4  description: |-
5    This is a sample Pet Store Server based on the OpenAPI 3.0 specification.
6paths:
7  "/pet":
8    put:
9      tags:
10      - pet
11      summary: Update an existing pet
12      description: Update an existing pet by Id
13      operationId: updatePet
14      requestBody:
15        description: Update an existent pet in the store
16        content:
17          application/json:
18            schema:
19              "$ref": "#/components/schemas/Pet"
20        required: true
21      responses:
22        '200':
23          description: Successful operation
24          content:
25            application/json:
26              schema:
27                "$ref": "#/components/schemas/Pet"
28        '400':
29          description: Invalid ID supplied
30        '404':
31          description: Pet not found
32        '405':
33          description: Validation exception
34      security:
35      - api_key
36components:
37  schemas:
38    Category:
39      type: object
40      properties:
41        id:
42          type: integer
43          format: int64
44          example: 1
45        name:
46          type: string
47          example: Dogs
48    Tag:
49      type: object
50      properties:
51        id:
52          type: integer
53          format: int64
54        name:
55          type: string
56    Pet:
57      required:
58      - name
59      - photoUrls
60      type: object
61      properties:
62        id:
63          type: integer
64          format: int64
65          example: 10
66        name:
67          type: string
68          example: doggie
69        category:
70          "$ref": "#/components/schemas/Category"
71        photoUrls:
72          type: array
73          items:
74            type: string
75        tags:
76          type: array
77          items:
78            "$ref": "#/components/schemas/Tag"
79        status:
80          type: string
81          description: pet status in the store
82          enum:
83          - available
84          - pending
85          - sold
86  securitySchemes:
87    api_key:
88      type: apiKey
89      name: api_key
90      in: header

Best practices

Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation:

  • Organize with proper project structure. Follow the instructions at Project structure to clearly organize the directories that contain your definition and other related files.
  • Add operationId to endpoints. Include a clear operationId for each endpoint to control the function names generated in your SDKs. (Or use extensions to customize group and method names.)
  • Reference schemas instead of inlining. Define reusable schemas in the components/schemas section and reference them with $ref. This promotes consistency, reduces duplication, and makes maintenance easier.
    Example of referencing schemas
    openapi.yml
    1paths:
    2  /pets:
    3    post:
    4      requestBody:
    5        content:
    6          application/json:
    7            schema:
    8              $ref: '#/components/schemas/Pet'  # Clean reference
    9      responses:
    10        '200':
    11          content:
    12            application/json:
    13              schema:
    14                $ref: '#/components/schemas/Pet'  # Reused easily
    15components:
    16  schemas:
    17    Pet:                        # Defined once, used everywhere
    18      type: object
    19      properties:
    20        name:
    21          type: string
    22        status:
    23          type: string
    24          enum: [available, pending, sold]
  • Use overlays and Fern extensions for customization. Customize your specification using Fern extensions housed in an overlay file. This lets you modify generation behavior without changing your core OpenAPI definition.

Once your OpenAPI spec follows these practices, you’re ready to set up your fern folder.

Set up your fern folder

Start by initializing your fern folder with an OpenAPI spec

1fern init --openapi ./path/to/openapi

This will initialize a directory like the following:

fern
fern.config.json
generators.yml
openapi
openapi.yml# Your spec