OpenAPI for beginners: write your first contract in 20 minutes

If you build APIs but have never sat down to write an openapi.yaml, it is normal for the specification to feel distant or overly formal. In practice, OpenAPI is simply a standard way to describe how to talk to your API in a file that both humans and tools can understand.

In this tutorial you will create your first OpenAPI contract from scratch, understand what each block represents, and see how that file automatically becomes navigable documentation. You do not need to know every detail of the spec; with a few core concepts you can start working in a much more structured way.

What OpenAPI is (in plain language)

OpenAPI is a format for describing HTTP APIs in a file (usually YAML or JSON). In that file you define things like:

Which endpoints exist (for example /tasks, /users).
Which methods they accept (GET, POST, etc.).
Which parameters they expect (query, path, headers, body).
Which responses they return (status codes, data models, errors).
How callers authenticate against the API.

Think of it as a technical map of your API. That map can be read by humans, but also by visual editors, documentation generators, SDK generators, and testing tools. That is why it makes sense to invest a few minutes in defining it properly: everything else becomes easier to automate.

The minimal anatomy of an OpenAPI file

A basic openapi.yaml file usually has five important sections:

openapi: the specification version you are using.
info: general information about your API (title, description, version).
servers: base URLs where your API lives.
paths: concrete routes and methods (/tasks, GET, POST, etc.).
components: reusable models (for example, the Task schema).

From there you can add security, global parameters, common responses, and plenty of other details, but you do not need all of that to get started. With a minimal structure you can already describe a simple API and visualize it as documentation.

Your first example API: a tasks API

Imagine you want to document a very simple API with a single endpoint:

GET /tasks: returns the list of tasks.

Let us build openapi.yaml step by step. First, the header with the version, basic information, and server:

openapi: 3.0.3
info:
  title: Tasks API
  version: 1.0.0
  description: Example API for managing tasks
servers:
  - url: https://api.example.com

Now add the /tasks path with a GET operation and a 200 response that returns an array of tasks. To do that, we will also create a Task schema under components.schemas:

openapi: 3.0.3
info:
  title: Tasks API
  version: 1.0.0
  description: Example API for managing tasks
servers:
  - url: https://api.example.com
paths:
  /tasks:
    get:
      summary: List all tasks
      description: Returns all tasks visible to the authenticated user.
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "Buy milk"
        completed:
          type: boolean
          example: false

With this snippet you are already describing:

That there is a GET /tasks endpoint.
That it returns a 200 status code with an application/json body.
That the body is an array of Task objects.
Which fields Task has and what type each field is.

We have not defined authentication, errors, or other endpoints yet, but you already have a useful baseline to share your API and generate documentation.

Seeing your spec as visual documentation

One of the nicest aspects of OpenAPI is that you can paste your openapi.yaml into a visual editor and get a navigable documentation portal without writing any HTML. Tools like Swagger Editor and other online alternatives let you:

See the list of endpoints in a side menu.
Expand each operation to inspect parameters and responses.
Try out calls directly from the browser if the server is configured correctly.

The basic flow looks like this:

Renderizando diagrama…

In other words: once you have the OpenAPI contract, that file becomes the source of truth feeding docs, tests, mocks, and clients. You no longer need to rewrite the same information in multiple places.

Beyond generic editors, you can work directly on your contract inside Capydox: the workspace includes an OpenAPI editor that behaves like a Swagger-style viewer and lets you import an existing spec, generate richer documentation, and, if you already work with test collections, convert collections into OpenAPI contracts or the other way around (creating collections from your swagger). This keeps contract, docs, and test evidence together in one place.

Why writing OpenAPI makes sense even for small projects

It can be tempting to think that OpenAPI is a heavy tool reserved for large companies or public APIs with thousands of users. In practice, small projects benefit even more:

You avoid forgetting details: having to define parameters, models, and responses forces you to think through your API design.
You help your future self: when you come back months later, the contract reminds you how each endpoint behaves without having to read all the code.
You unlock automation: even if you initially use the spec only to generate docs, later you can add CI validations, mocks, SDKs, and more.

In a team setting, OpenAPI becomes the shared language between backend, frontend, QA, and any external integrators. Everyone talks about the same thing: the contract.

Next steps and where Capydox fits

Once your first openapi.yaml is working, the next level is integrating that contract into your normal workflow:

Version the file alongside your code in Git.
Review contract changes through pull requests, just like code changes.
Add automated checks to validate the spec before deployments.

From there you can start connecting tools around that contract. Capydox, for example, can use your OpenAPI file as raw material to generate richer documentation, link it with test evidence, and help keep docs aligned with what is actually running in your environments.

The underlying idea is simple: the sooner you turn your API into an explicit contract, the easier it becomes to document, test, and evolve it without surprises.

OpenAPI for beginners: write your first contract in 20 minutes