Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First OpenAPI Document: Build a Pet Store API Step by Step

Write a complete OpenAPI 3.1 document from scratch: info, servers, one path, parameters, a response schema and an error. Includes a live checker stand-in.

The best way to understand OpenAPI is to write a document. In this lesson you build a small but real description of a pet-store API in four steps, adding one idea at a time. You only need a text editor; any file named openapi.yaml works.

Step 1: the skeleton

Every document needs three things at the root: the specification version, basic information about the API, and the paths it offers.

YAML
openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
  description: A tiny API for managing pets.
paths: {}

info.version is the version of your API, not of OpenAPI. paths: {} is valid but empty. (In OpenAPI 3.1 a document must contain at least one of paths, components or webhooks.)

Step 2: tell callers where the API lives

Add a servers list. Each entry is a base URL; paths are appended to it.

YAML
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:8080/v1
    description: Local development

If you leave servers out, tools assume the API is served from / on the same host as the document.

Step 3: add the first operation

An operation is one HTTP method on one path. Here is GET /pets, which returns a list.

YAML
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets
      parameters:
        - name: limit
          in: query
          description: Maximum number of pets to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: A page of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, name]
                  properties:
                    id:   { type: integer }
                    name: { type: string }
                    tag:  { type: string }

Read it aloud: "Calling GET /pets with an optional limit query parameter answers 200 with JSON: an array of objects that always have an id and a name, and may have a tag."

  • operationId is a unique name for the operation. Generators use it as the function name (listPets).
  • Status codes are written as strings ("200") because they are YAML map keys; quoting avoids surprises.

Step 4: one operation with a path parameter and an error

YAML
  /pets/{petId}:
    get:
      operationId: getPet
      summary: Get one pet
      parameters:
        - name: petId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The pet
          content:
            application/json:
              schema:
                type: object
                required: [id, name]
                properties:
                  id:   { type: integer }
                  name: { type: string }
        "404":
          description: No pet with that id

The in the URL must match a parameter with in: path, and path parameters are always required: true.

Check it with a stand-in

Real validators (see tooling) check hundreds of rules. This stand-in checks five of the most basic ones so you can feel how linting works. Change the document, break a rule, and run it again.

Python Stand-in: a tiny document checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Viewing your document

Paste the YAML into an online or local viewer (such as Swagger Editor or Redoc, covered in Documentation tools) and you get a rendered reference page: a list of operations, a form with a Try it out button, and the response schemas. No server is needed to see the documentation.

flowchart TD
  R["openapi, info, paths"] --> S["add servers"]
  S --> P1["GET /pets"]
  P1 --> P2["GET /pets/{petId}"]
  P2 --> V["view in an editor or viewer"]

Each step above only adds fields; the document is valid after every one.

Common first-document mistakes

  • Wrong indentation. YAML uses spaces, never tabs. One misplaced level moves a key into the wrong object.
  • Unquoted 200. Some tools complain; always write "200".
  • Missing required: true on path parameters.
  • Forgetting that version is a string (1.0.0, not a number).
  • Putting description where a summary is expected. summary is a short title; description is longer text and may use Markdown.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which top-level fields did the very first document in this lesson need?

    A minimal document has the specification version, the info object and the paths object.
  2. 2. What does info.version refer to?

    openapi is the spec version; info.version is the version of your own API.
  3. 3. A path is /pets/{petId}. What must the matching parameter look like?

    Path template variables need a declared path parameter, always required.
  4. 4. What is operationId for?

    operationId must be unique in the document and becomes method names in generated code.

Summary

  • A document starts with openapi, info and paths.
  • servers lists base URLs; operations hang under a path and an HTTP method.
  • Path parameters are always required: true; status codes are quoted strings.
  • operationId should be unique; generators use it for function names.
  • A small checker, like a real linter, finds structural mistakes before a human has to.

Next: Tooling: editors, linters and viewers