HTTP JSON Endpoints | Fern Documentation

Endpoints in OpenAPI are defined underneath the paths key. Below is an example of defining a single endpoint:

openapi.yml

paths:
  /pets:
    post:
      summary: Create a new pet
      description: Creates a new pet with the provided information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

Response handling

Fern keeps one success response per operation. When an operation declares several 2XX responses, Fern picks the first match in the order 200, 201, 202, 204 and drops the others. Only responses in the 400–600 range are classified as errors.

The wildcard response keys 4XX and 5XX are imported as errors named ClientRequestError and ServerError. A wildcard covers every status in its range that the operation doesn’t declare explicitly, so a 404 response takes precedence over 4XX. Wildcards work in the spec itself or in an overlay, and the Go SDK generator decodes them into typed errors that preserve the actual response status code. Other generators map 4XX to 400 and 5XX to 500. default responses aren’t classified as errors.

openapi.yml

responses:
  '200':
    description: Success
  '4XX':
    description: Caller error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ApiError'
  '5XX':
    description: Server error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ApiError'

Type error response bodies

If error responses have no body schema, set error-responses in generators.yml to give them a shared typed body in SDKs and API References. Set apply-to: untyped to keep existing typed errors, or use the default all to replace the body schemas of every 4xx/5xx response. This applies across OpenAPI specs without separate overlays for each one.

Examples

You can provide examples of requests and responses by using the examples key. If a body has no media-type examples, Fern falls back to the schema-level examples on the body schema.

openapi.yml

paths:
  /pets:
    post:
      summary: Create a new pet
      description: Creates a new pet with the provided information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            examples:
              PetExample:
                summary: This is an example of a Pet
                value: 
                  name: Markley
                  id: 44
      responses:
        '200':
          description: A Pet object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
              examples:
                PetExample:
                  summary: This is an example of a Pet
                  value: 
                    name: Markley
                    id: 44