Design a REST API with OpenAPI and Swagger

August 15, 2026 Khimananda Oli 7 min read Virtualization

By Khimananda Oli | Last reviewed: August 2026

Most backend teams waste weeks rewriting documentation because they treat specs as an afterthought rather than the source of truth. When you design a REST API with OpenAPI and Swagger first, you align frontend, backend, and QA around a single machine-readable contract before writing implementation code. This guide walks through the exact contract-first workflow I use to ship stable, well-documented APIs that pass security reviews and integrate smoothly with observability tools like those in my OpenTelemetry observability standard guide.

Quick answer: To design a REST API with OpenAPI and Swagger, define your endpoints, schemas, and responses in an OpenAPI 3.1 YAML file first, validate it with Spectral or Swagger Editor, then generate server stubs and client SDKs. This contract-first approach ensures documentation accuracy and accelerates development.

Figure 1: The four-stage contract-first workflow to design a REST API with OpenAPI and Swagger effectively.

How do you design a REST API with OpenAPI and Swagger using the contract-first method?

The contract-first method flips the traditional "code-then-document" approach. Instead of retrofitting docs onto existing controllers, you write the OpenAPI Specification (OAS) as the primary artifact. This specification serves as the executable agreement between stakeholders. In practice, this reduces integration bugs by forcing edge-case discussions before a single line of business logic exists.

Step 1: Define the info and server blocks

Start every spec with clear metadata. Versioning here prevents breaking changes later. Always include at least one server URL so generated clients know where to send requests during testing.

openapi: 3.1.0
info:
  title: Inventory Management API
  version: 1.2.0
  description: Manages warehouse stock levels and audit trails.
  contact:
    name: Platform Team
    email: [email protected]
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:8080/v1
    description: Local Development

Step 2: Model reusable schemas with components

Never inline complex objects repeatedly. Use the components/schemas section to define data models once. This keeps your paths clean and ensures consistency across GET, POST, and PATCH operations. For teams managing database schemas alongside APIs, aligning these models early prevents drift; see my notes on PostgreSQL administration essentials for schema governance patterns.

components:
  schemas:
    Product:
      type: object
      required: [sku, name, quantity]
      properties:
        sku:
          type: string
          pattern: '^[A-Z]{2}-\d{4}$'
        name:
          type: string
          maxLength: 100
        quantity:
          type: integer
          minimum: 0
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

Step 3: Map paths to operations explicitly

Define each endpoint with its HTTP verb, parameters, request body, and response codes. Be specific about status codes: distinguish between 200 OK, 201 Created, and 204 No Content. Vague responses are the most common cause of client-side parsing errors in production.

GET /products/{sku}: Returns a single Product or 404 Error.
POST /products: Accepts a Product payload, returns 201 with Location header.
PATCH /products/{sku}/quantity: Partial update for inventory adjustments only.

What is the difference between Swagger and OpenAPI in 2026?

Confusion persists because "Swagger" was renamed to "OpenAPI" in 2017, yet many tools retain the old branding. Understanding this distinction matters when selecting dependencies and avoiding deprecated libraries.

Feature	Swagger 2.0	OpenAPI 3.1
JSON Schema Alignment	Custom dialect (draft-4 subset)	Full JSON Schema 2020-12 compatibility
Webhooks Support	No	Native top-level webhooks object
Multiple Servers	Single host/basePath only	Array of server objects with variables
Content Negotiation	Limited per-operation	Granular media-type level definitions
Tooling Status (2026)	Maintenance mode / Legacy	Active standard, default for new projects

In short: Swagger 2.0 is legacy. When you design a REST API with OpenAPI and Swagger today, you are actually using the OpenAPI 3.1 specification with Swagger-branded tooling (like Swagger UI or Swagger Codegen). Always target OAS 3.1 for new work to leverage full JSON Schema support and webhook definitions.

Figure 2: Anatomy of an OpenAPI 3.1 spec — understanding this hierarchy is critical when you design a REST API with OpenAPI and Swagger.

How do you validate and lint OpenAPI specifications automatically?

A spec that fails validation breaks CI pipelines and generates faulty SDKs. Never rely solely on visual inspection. Automated linting catches structural errors, naming inconsistencies, and missing descriptions before they reach code review.

Install Spectral CLI: The industry-standard linter for OAS 3.x. Run npm install -g @stoplight/spectral-cli.
Create a ruleset: Extend the built-in OAS ruleset and add custom rules for your team’s conventions (e.g., requiring x-slo-latency extensions).
Integrate into CI: Add spectral lint openapi.yaml as a mandatory gate in your GitHub Actions or GitLab CI pipeline.
Fail fast on warnings: Treat documentation gaps (missing summaries, untyped parameters) as errors, not warnings. Ambiguity in specs becomes ambiguity in production behavior.

# .spectral.yaml
extends: spectral:oas
rules:
  operation-description: error
  parameter-description: warn
  custom-version-format:
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: ^\d+\.\d+\.\d+$
    severity: error
    message: "Version must follow strict SemVer."

This discipline pairs naturally with infrastructure-as-code practices. Just as you would never deploy unvalidated Terraform, never ship an unlinted API contract. Teams adopting infrastructure as code with Terraform often apply the same rigor to API specs, treating both as versioned, tested artifacts.

Which tools generate code and docs from OpenAPI specs reliably?

Once your spec is validated, leverage generators to eliminate boilerplate. The ecosystem has matured significantly; choose tools based on language support, maintenance activity, and customization depth.

Swagger Codegen / OpenAPI Generator: Supports 50+ languages. Best for generating server stubs (Spring Boot, Express, Go) and client SDKs. Fork and customize templates if defaults don’t match your internal standards.
Swagger UI: Renders interactive HTML docs directly from the spec. Embed it in your API gateway or serve statically. Ensure it points to the exact spec version deployed, not a generic latest link.
Redoc: Cleaner, three-column layout preferred for public-facing APIs. Better typography and navigation than Swagger UI for large specs.
Orval / Hey API: Modern TypeScript-focused generators producing typed fetch/axios clients with built-in validation. Ideal for frontend-heavy teams consuming your API.

A common mistake is generating code once and abandoning the spec. Regenerate on every spec change. Store generated code in CI artifacts or commit it with clear markers indicating it is auto-generated. Manual edits to generated files will be overwritten and lost.

Figure 3: Output targets when you design a REST API with OpenAPI and Swagger — servers, clients, and docs all derive from one source.

How do you maintain API contracts across microservices?

In distributed systems, specs drift. Centralize your OpenAPI files in a dedicated repository or monorepo path. Use semantic versioning strictly: bump major versions for breaking changes, minor for additive ones. Tag releases in Git matching the info.version field.

Implement backward compatibility checks in CI using tools like oasdiff or breaking-changes-detector. These compare the current spec against the last released version and fail the build if incompatible modifications slip through. This automation is non-negotiable for teams operating multiple services where consumers cannot upgrade synchronously.

For Nepal-based teams building regional fintech or e-commerce platforms, consider data residency implications in your spec. Document region-specific endpoints or data handling requirements using vendor extensions (x-data-residency: np). This makes compliance auditable directly from the contract, supporting frameworks discussed in data protection basics for Nepal fintech.

Design a REST API with OpenAPI and Swagger: Next Steps

Treating your API specification as a first-class engineering artifact transforms how teams collaborate, test, and scale. When you design a REST API with OpenAPI and Swagger using the contract-first workflow outlined here, you reduce rework, accelerate onboarding, and create self-documenting systems that survive team turnover. Start small: pick one upcoming feature, write the spec before coding, validate it in CI, and generate at least one client SDK. Measure the reduction in integration issues over two sprints. If you need help establishing this workflow for your team or auditing existing API contracts for compliance and quality, reach out to discuss your architecture.

Frequently Asked Questions

OpenAPI is the specification standard for REST APIs, while Swagger refers to the toolset originally created by SmartBear. Since 2016, the spec has been governed by the OpenAPI Initiative. Use OpenAPI 3.1 for defining contracts and Swagger UI or Editor for visualization and testing in 2026.

Use OpenAPI 3.1.0 as it aligns fully with JSON Schema 2020-12 and supports webhooks. Version 3.0.3 remains stable but lacks newer schema features. Avoid Swagger 2.0 entirely as it is deprecated and incompatible with modern code generation tools and validation libraries used in current DevOps pipelines.

Use spectral-cli or openapi-generator-cli validate in your pipeline. Add a linting step that fails builds on errors or warnings. Configure custom rulesets to enforce team standards like naming conventions, security scheme requirements, and response structure consistency before merging pull requests to main branches.

Yes, openapi-generator supports over fifty languages including Go, Python, and PHP Laravel. Generate boilerplate controllers, models, and routing configurations directly from your spec. This ensures implementation matches documentation exactly and reduces manual coding errors during initial API scaffolding or major version refactors in production environments.

Define securitySchemes under components using apiKey, http bearer, or oauth2 types. Reference them globally or per-operation via the security field. Specify token endpoints, scopes, and flows explicitly so generated clients handle auth correctly and Swagger UI provides interactive authorization buttons for testers and frontend developers.

Yes, Swagger UI is Apache 2.0 licensed and free for commercial use. You can self-host the static assets without cost. Paid alternatives exist for hosted docs with analytics, but the core open-source renderer meets most internal and external API documentation needs without licensing fees or vendor lock-in.

Use $ref pointers to reference external YAML or JSON files for paths, schemas, and parameters. Tools like swagger-cli bundle these references into a single file for deployment. Organize by domain resource to maintain readability while keeping the master spec clean and manageable for large teams.

For Laravel, use scribe or laravel-openapi. In Node.js, try tsoa or routing-controllers-openapi. These parse annotations or route definitions to produce specs automatically. Combine with manual overrides for complex scenarios. Always review generated output against actual behavior since reflection-based tools may miss edge cases or dynamic routes.

Include version in the info object and path prefix like /v1/users. Maintain separate spec files per major version rather than mixing versions in one document. Use server variables for environment-specific base URLs. Deprecate old operations with the deprecated flag while providing migration guidance in descriptions for consuming teams.

No, OpenAPI only covers synchronous REST over HTTP. Use AsyncAPI for WebSockets, Kafka, or event-driven architectures. Some teams maintain both specs side-by-side with shared schema references. Do not force async patterns into OpenAPI as tooling will ignore or misinterpret non-REST constructs causing documentation drift.

Run Swagger UI locally with docker compose pointing to your spec file. Use the Try it out feature to execute real requests against dev servers. Pair with Prism mock server for contract testing without backend dependencies. This validates examples, parameter handling, and error responses before integration testing begins.

Missing required fields in request bodies, undefined schema references, duplicate operationIds, and incorrect content-type declarations cause frequent failures. Ensure all $ref targets exist and response codes match actual implementations. Validate early with spectral to catch structural issues before they propagate through code generation or documentation publishing workflows.

Never expose raw spec files publicly unless intended for external consumers. Serve through authenticated gateways or restrict access via IP allowlists. Strip internal-only endpoints and sensitive example data before publishing. Treat specs as infrastructure code requiring the same access controls and audit trails as application source repositories.

Yes, define requestBody with multipart/form-data or application/octet-stream media types. Specify encoding properties for file fields including contentType and headers. For binary responses, set content to application/octet-stream with format binary in schema. Test thoroughly as some generators handle streaming differently than standard JSON payloads.

Update specs in the same pull request as code changes using spec-first or design-first workflows. Treat the OpenAPI file as the source of truth, not afterthought documentation. Automate validation and doc regeneration in CI so published docs always reflect deployed behavior. Review specs during sprint planning to align frontend and backend contracts early.