Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Specification Basics

OpenAPI Info, Servers, Server Variables and Tags

Fill in the descriptive part of an OpenAPI document: the info object, contact and license, servers with variables, tags and external docs, plus a URL resolver.

Before paths and schemas, an OpenAPI document tells readers who the API is for, where to call it and how its operations are grouped. These fields are small, but they are the first thing people see in your documentation, so they are worth getting right.

The info object

YAML
info:
  title: Library API
  summary: Books, authors and loans.
  description: |
    The Library API lets partner apps search the catalog and
    manage loans. **Rate limit:** 100 requests per minute.
  termsOfService: https://example.com/terms
  contact:
    name: API Support
    url: https://example.com/support
    email: [email protected]
  license:
    name: Apache 2.0
    identifier: Apache-2.0
  version: 2.3.1
  • title and version are required. version describes your API (any string; semantic versioning is common).
  • summary (3.1) is a one-line tagline. description is longer and supports CommonMark (Markdown), so use headings, lists and code samples for getting-started notes.
  • license takes either url or the SPDX identifier, not both.

Servers

servers lists base URLs. Every path is appended to the server URL.

YAML
servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://sandbox.example.com/v2
    description: Sandbox with fake data

Rules worth knowing:

  • Relative URLs are allowed and are resolved against the location of the document (url: /v2).
  • If servers is missing or empty, the default is a single server with url: /.
  • You can also set servers on a path item or an operation to override the list for just that part (for example a file-upload endpoint on a different host).

Server variables

Variables let one entry describe many URLs. Put names in braces and give each a default:

YAML
servers:
  - url: https://{region}.api.example.com/{version}
    description: Regional API
    variables:
      region:
        default: eu
        enum: [eu, us, ap]
        description: Data center
      version:
        default: v2

The default is required (tools use it when the user does not pick another value). Always list every allowed value in enum when the set is closed.

Resolving server URLs: a stand-in

A documentation tool substitutes variables to build the real URL it sends requests to. This stand-in does the same and rejects values outside the enum.

Python Stand-in: resolve a server URL with variables

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.

Tags

A tag is a label that operations carry to be grouped in documentation. Operations list tag names; the root tags array adds a description and fixes the display order.

YAML
tags:
  - name: books
    description: Search and manage books.
    externalDocs:
      description: Catalog rules
      url: https://example.com/docs/catalog
  - name: loans
    description: Check books in and out.

paths:
  /books:
    get:
      tags: [books]
      summary: List books
      responses:
        "200": { description: OK }

Notes:

  • An operation may have several tags; documentation tools usually show it under each.
  • Tags used by an operation but not declared at the root still work. They just have no description, and their order is not guaranteed.
  • Tag names are case sensitive, so Books and books are two different groups.
  • Common practice is one tag per resource (books, loans), not per HTTP method.

External documentation

externalDocs can appear at the root, on a tag, an operation or a schema:

YAML
externalDocs:
  description: Full integration guide
  url: https://example.com/guide

Show the group view

This stand-in builds the grouped table of contents that documentation tools build from tags, including the "default" group for untagged operations.

Python Stand-in: group operations by tag

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.

Practical advice

  • Write the description for a new developer: what the API is for, how to get access, rate limits, versioning policy.
  • Keep title stable; tools use it for file names and package names in generated code.
  • Put sandbox and production in servers so "Try it out" can be pointed at a safe environment.
  • Do not put secrets, tokens or internal hostnames in servers or info: the document is usually public.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two fields of the info object are required?

    Only title and version are required; everything else is optional.
  2. 2. What happens when servers is omitted?

    The default is a server whose URL is /, relative to the document location.
  3. 3. What is required in every server variable?

    Each variable must have a default; enum and description are optional.
  4. 4. Where do you add a description for the tag loans?

    The root tags array holds names, descriptions and external docs; operations only reference names.

Summary

  • info introduces the API: required title and version, optional Markdown description, contact and license.
  • servers hold base URLs; variables substitute pieces and always need a default.
  • Servers can be overridden per path item or operation.
  • Tags group operations in documentation; declare them at the root to add descriptions and control order.

Next: YAML and JSON syntax for OpenAPI