OpenAPI Structure — Info, Paths, and Components sections

In this tutorial, you will learn about OpenAPI Structure. We cover key concepts, practical examples, and best practices to help you master this topic.

The OpenAPI specification has a well-defined structure with four main top-level sections: info for metadata, servers for base URLs, paths for endpoints, and components for reusable definitions.

What You'll Learn

• Top-level OpenAPI objects and their purposes
• How info, servers, paths, and components work together
• Best practices for organizing each section

Structure Overview

openapi: "3.0.3"
info:
  title: API Title
  description: Description
  version: "1.0.0"
  contact:
    name: API Team
    url: https://example.com/support
  license:
    name: Apache 2.0

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging.api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: OK

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Code Examples

# Validating OpenAPI structure
from openapi_spec_validator import validate_spec

with open("openapi.yaml") as f:
    spec = yaml.safe_load(f)

validate_spec(spec)
print("OpenAPI spec is valid")

# Check required fields
required = ["openapi", "info", "paths"]
for field in required:
    if field not in spec:
        print(f"Missing required field: {field}")

// Parsing OpenAPI in Node.js
const YAML = require('yaml');
const fs = require('fs');

const spec = YAML.parse(fs.readFileSync('openapi.yaml', 'utf8'));
console.log('API:', spec.info.title);
console.log('Version:', spec.info.version);
console.log('Endpoints:', Object.keys(spec.paths));

Common Mistakes

1. Missing Info Version

Every spec must have a version. Use semantic versioning (1.0.0).

2. No Server URLs

Without servers, tools don't know where to send requests.

3. Forgetting components/schemas

Define reusable schemas in components to avoid duplication.

4. Empty Paths Object

The paths object must contain at least one path.

5. Missing OpenAPI Version Declaration

The openapi field must be "3.0.0" or later.

Practice Questions

1. What are the four main sections of an OpenAPI spec?
2. Why is the info section important?
3. How do servers help documentation tools?
4. What is stored in components/schemas?
5. What happens if the openapi version field is missing?

Answers:

1. openapi, info, servers, paths, components.
2. It provides metadata like title, version, and contact info.
3. Servers give tools the base URL for making test requests.
4. Reusable data type definitions that can be referenced from paths.
5. The spec is invalid and won't be parsed by OpenAPI tools.

Challenge: Create a complete OpenAPI spec with at least one path that references a component schema for the request and response bodies.

FAQ

What's Next

Explore OpenAPI Paths for defining endpoints, then learn about OpenAPI Parameters.