TopolearnEverything you write later lives in one of these few sections.
An OpenAPI document is one object (YAML is most common; JSON is equivalent). Its top-level fields:
openapi(required): the spec version, e.g.3.1.1. Tools use it to choose parsing rules.info(required):title,version(of your API, not the spec), plus optionaldescription(Markdown),contact,license.servers: base URLs such ashttps://api.example.com/v1. Paths are appended to them; server variables allow templating likehttps://{region}.api.example.com.paths: the endpoints and their operations. In 3.1 a document may have no paths at all, for example when it only defines webhooks or shared components.components: reusable schemas, parameters, responses, request bodies, examples, headers and security schemes.security: the default security requirement for all operations.tags: groups for operations, with descriptions shown in docs.webhooks(3.1+): requests your API sends to subscribers.
Any object can carry specification extensions, fields starting with x- (x-internal: true), which tools may interpret.
Large APIs are split across files and joined with $ref to relative files ($ref: './schemas/user.yaml'). Bundlers like redocly bundle produce a single file for tools that need one.
Example
openapi: 3.1.1
info:
title: Bookstore API
version: 2.3.0 # version of YOUR API
description: Manage books and orders.
contact: { email: api@example.com }
servers:
- url: https://api.example.com/v2
description: Production
- url: https://{region}.sandbox.example.com/v2
variables:
region: { default: eu, enum: [eu, us] }
tags:
- name: books
description: Catalogue operations
security:
- bearerAuth: []
paths: {} # operations go here
components:
securitySchemes:
bearerAuth: { type: http, scheme: bearer }Remember
openapi= spec version;info.version= your API's version- Paths are appended to
serversURLs componentsholds everything reusablex-fields are extensions for tools
Watch out for
- Putting the spec version in
info.versionor vice versa.