Stoplight’s OpenAPI (Swagger) designer is a powerful tool for defining, documenting, and governing your APIs. It’s not just about generating documentation; it’s about creating a single source of truth for your API’s contract.
Here’s a typical workflow:
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: List all users
responses:
'200':
description: A list of users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description: User created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/users/{userId}:
get:
summary: Get a user by ID
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: User found.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
required:
- id
- name
- email
NewUser:
type: object
properties:
name:
type: string
email:
type: string
format: email
required:
- name
- email
This YAML defines an API with endpoints for listing, creating, and retrieving users. Notice the use of $ref for reusable components like User and NewUser schemas. This promotes consistency and reduces redundancy.
Stoplight’s core value lies in its ability to enforce this contract. When you design your API in Stoplight, you’re not just writing documentation; you’re defining a schema that can be used for:
- Code Generation: Generate server stubs and client SDKs in various languages, ensuring your code adheres to the API contract.
- Automated Testing: Create mock servers and use generated clients to test your API endpoints against the defined schema.
- API Governance: Set up rules and policies to ensure API designs meet your organization’s standards before they are implemented.
- Collaboration: Provide a central place for developers, product managers, and designers to collaborate on API definitions.
Internally, Stoplight leverages the OpenAPI Specification (OAS) as its primary data model. It provides a rich UI for editing this specification, with features like auto-completion, schema validation, and a visual representation of your API. When you save changes, Stoplight updates the underlying OpenAPI document. This document then becomes the source of truth for all subsequent operations.
The components section is where you define reusable elements like schemas, parameters, and responses. This is crucial for maintaining a clean and DRY (Don’t Repeat Yourself) API definition. For example, defining a User schema once and referencing it across multiple paths ensures that the structure of a user object is consistent everywhere it’s used.
When you define parameters, like the userId in the /users/{userId} path, you specify its in (path, query, header, cookie), name, required status, and schema. This level of detail is what allows for precise code generation and robust validation.
The responses section, particularly the content and schema within it, defines what your API is expected to return. This is vital for consumers of your API to understand the data structures they will receive.
A subtle but powerful aspect of Stoplight’s design approach is how it handles versioning. While not explicitly shown in this basic example, Stoplight encourages a structured approach to API versioning, often through path parameters (e.g., /v1/users) or a dedicated version field in the info object. This allows you to evolve your API without breaking existing clients.
The most impactful aspect of using Stoplight for API design is its ability to shift API development from an implementation-first, documentation-later approach to a design-first, contract-driven methodology. This paradigm shift significantly reduces integration issues, improves developer experience, and ensures API consistency across an organization.
Beyond basic schema definitions, Stoplight supports advanced OpenAPI features like discriminators for polymorphism, examples for illustrating request/response bodies, and external documentation links. Understanding these advanced features unlocks even greater power in API design and governance.
The next step after defining your API contract is often to integrate it with a CI/CD pipeline for automated validation and deployment.