Skip to main content

Schema Basics

The foundation of the OAS is a the OpenAPI object, which in turn consits of a couple of objects. This object contains all the endpoints and its options of the API as well as metadata, general schema definitions and so on.

Root Object

The OpenAPI Object is the root object of the specification document. The most relevant fields are:

  • openapi: required, version of the specification
  • info: required, Info object with metadata about the API
  • servers: Array of Server Objects hosting the API, defaults to server with url /
  • paths: required: The available endpoints and methods of the API (more details later)

It also has additional fields to define common schemes for:

  • components: defines schemas
  • security: Security mechanisms that can be used (authentication, authorization)
  • webhooks: possibility to define webhook paths

Here are examples for YAML and JSON format with the same content:

openapi: 3.0.2
info:
title: Firebit API
version: 1.0.0
description: "API for the [Firebit](https://firebit.com) platform, a place to share experiences with your friends"
termsOfService: https://firebit.com/tos
servers:
...
paths:
...

As you can see, the YAML version is a bit shorter and (maybe) easier to read, because no brackets, quotes or commas are necessary.

Info Object

The Info object provides metadata of the API.

It has the fields:

  • title: required
  • version: required, version of the API
warning

Don't confuse the version of the Info object (version of the API) with the openapi field version (specification version).

Servers Object

This specifies a single server or list of servers, where the API is hosted. Requests sent from the documentation (like Swagger UI) will be sent to the selected server from this object.

It has the following ields:

  • url: required, URL to the host
  • description: optional name

Components Object

The components object allows to define objects in a single place and use them in many places.

This object is a list of reusable objects of various types. For each type, a field is provided, which is an map with the name as key and the structure as value.

It holds:

  • Schemas
  • PathItems
  • Parameters
  • RequestBodies
  • Headers
  • Responses
  • SecuritySchemes
  • etc.

Some examples are a "page" parameter, a "Not Found" response or an authentication method used for multiple operations.

An item in on of the lists is a Schema object, which defines the data type of the object.

For example:

#primitive
type: integer
format: int64

# object "model"
type: object
properties:
firstname:
type: string
age:
type: integer
Quiz

You can now do the first quiz "OpenAPI Basics".