Swagger / OpenAPI files

Swagger is the tooling ecosystem around the OpenAPI Specification (OAS). This guide explains what Swagger/OpenAPI is, why it matters, how to write an OpenAPI (Swagger) file, tools to author/validate/generate code, best practices, security, versioning, testing, and CI/CD workflows — with concrete YAML examples you can use immediately.

1. What is Swagger / OpenAPI?

• OpenAPI Specification (OAS) is a standard format for describing REST APIs (endpoints, data models, errors, authentication, etc.).
• Swagger refers to the tools:
  • Swagger Editor
  • Swagger UI
  • Swagger Codegen / OpenAPI Generator
• The OpenAPI file (YAML or JSON) is the source of truth for your API.

2. Design approaches

1. Design-first: Write OpenAPI spec first → generate backend & SDKs.
2. Code-first: Write code → generate OpenAPI from annotations.

3. OpenAPI file structure

• openapi — spec version
• info — metadata
• servers — API base URLs
• paths — endpoints
• components — schemas, responses, security

4. Example OpenAPI 3.0 YAML (CRUD API)

openapi: 3.0.3
info:
  title: Simple Articles API
  description: API for managing articles.
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:8080/v1
    description: Local
paths:
  /articles:
    get:
      summary: List articles
      responses:
        "200":
          description: Paginated list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedArticles"
components:
  schemas:
    Article:
      type: object
      properties:
        id:
          type: string
        title:
          type: string

5. Common OpenAPI features

5.1 Parameters

Define reusable parameters under components.parameters.

5.2 Request bodies

Use requestBody with JSON schema.

5.3 Responses (reusable)

responses:
  "404":
    description: Not found
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"

5.4 Security schemes

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

6. Tools

• Swagger Editor
• Swagger UI
• Redoc
• OpenAPI Generator
• Spectral Linter
• Prism Mock Server

7. YAML vs JSON

YAML is preferred due to readability and comments.

8. Best practices

• Write specs API-first.
• Use $ref to reuse schemas.
• Add examples for clarity.
• Define standard error objects.
• Use tags for logical grouping.
• Version your API via /v1.

9. Advanced features

• Links
• Callbacks
• oneOf / allOf / anyOf
• File uploads

10. Code generation

# Generate NodeJS Express server
openapi-generator-cli generate -i openapi.yml -g nodejs-express-server
# Generate TypeScript client
openapi-generator-cli generate -i openapi.yml -g typescript-axios

11. Security

• No secrets inside spec.
• Document authentication clearly.
• Hide internal endpoints.

12. Versioning

• Use semantic versioning.
• Deprecate before removing fields.