Skip to content

Use Case 1: Quickstart — Build Your First OpenAPI-First Service

This guide walks you from an empty directory to a running, contract-driven service in a few minutes, then talks to it with the generated client.

🛠️ 1. Prerequisites

  • Python 3.10+
  • openapi-first installed (see Overview)
  • pip install "fastapi[standard]" (or uvicorn) to run the app

📄 2. Write the OpenAPI document

OpenAPI comes first. Create openapi.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
openapi: 3.0.3
info:
  title: Greeting Service
  version: 1.0.0
servers:
  - url: http://localhost:8000
paths:
  /greet/{name}:
    get:
      operationId: get_greeting
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A greeting
          content:
            application/json:
              schema:
                type: object
                properties:
                  greeting:
                    type: string

Key points: every operation needs operationId, and every route must exist only here.

🧑‍💻 3. Write the handlers

Create routes.py — plain functions, no decorators, named exactly like the operationIds:

1
2
3
4
# routes.py
def get_greeting(name: str) -> dict:
    """Return a greeting for the given name."""
    return {"greeting": f"Hello, {name}!"}

If a handler is missing at startup, the app refuses to boot (MissingOperationHandler) — the fail-fast guarantee catches contract drift immediately.

🚀 4. Bootstrap the app

Create main.py:

1
2
3
4
5
6
7
8
9
# main.py
from openapi_first.app import OpenAPIFirstApp
import routes

app = OpenAPIFirstApp(
    openapi_path="openapi.yaml",
    routes_module=routes,
    title="Greeting Service",
)

Run it:

1
uvicorn main:app --reload

Visit http://localhost:8000/docs (Swagger UI) and http://localhost:8000/openapi.json — both are generated from your spec.

📡 5. Call it with the client

The same spec builds a strict client:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# client.py
from openapi_first.loader import load_openapi
from openapi_first.client import OpenAPIClient

spec = load_openapi("openapi.yaml")
client = OpenAPIClient(spec)

response = client.get_greeting(path_params={"name": "Ada"})
print(response.status_code)   # 200
print(response.json())        # {"greeting": "Hello, Ada!"}

💡 6. Next Steps