API Documentation with Stoplight: Practical Examples

Explore practical examples of using Stoplight for effective API documentation.
By Jamie

Introduction to Stoplight for API Documentation

Stoplight is a powerful tool designed to streamline the process of creating, maintaining, and publishing API documentation. Its intuitive interface and robust features make it an ideal choice for developers and technical writers looking for clarity and efficiency in documentation. Here, we present three diverse and practical examples of using Stoplight for API documentation, demonstrating its capabilities across different scenarios.

Example 1: RESTful API Documentation for a Weather Service

Context

A developer team is working on a weather API that provides current weather data and forecasts for various locations. They want to ensure that the API documentation is clear and easy to navigate for both internal and external developers.

Using Stoplight, they can create comprehensive documentation that includes all necessary information in a structured format.

## Weather API Documentation

openapi: 3.0.0
info:
  title: Weather API
  description: API for retrieving weather data.
  version: 1.0.0
servers:

  - url: https://api.weather.com/v1

paths:
  /current:
    get:
      summary: Get Current Weather
      parameters:

        - in: query
          name: location
          required: true
          description: Location to retrieve weather for
          schema:
            type: string
      responses:
        '200':
          description: Successful response with current weather
          content:
            application/json:
              schema:
                type: object
                properties:
                  temperature:
                    type: number
                  condition:
                    type: string

  /forecast:
    get:
      summary: Get Weather Forecast
      parameters:

        - in: query
          name: location
          required: true
          description: Location to retrieve forecast for
          schema:
            type: string
      responses:
        '200':
          description: Successful response with weather forecast
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date
                    temperature:
                      type: number
                    condition:
                      type: string

Notes

  • This YAML snippet utilizes OpenAPI 3.0 specification, which is supported by Stoplight.
  • Developers can easily test API endpoints directly within Stoplight, enhancing the documentation’s interactivity.

Example 2: API Documentation for a E-commerce Platform

Context

An e-commerce platform is developing a new API to manage product listings, orders, and user accounts. The documentation needs to cover multiple endpoints and provide clear examples for integration.

Stoplight helps create well-organized documentation with examples that developers can reference easily.

## E-commerce API Documentation

openapi: 3.0.0
info:
  title: E-commerce API
  description: API for managing e-commerce operations.
  version: 1.0.0
servers:

  - url: https://api.ecommerce.com/v1

paths:
  /products:
    get:
      summary: Retrieve Product List
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    price:
                      type: number
  /orders:
    post:
      summary: Create a New Order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                productIds:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string

Notes

  • The provided examples include both GET and POST methods to explain different API interactions.
  • Developers can utilize Stoplight’s mock server feature to simulate API responses.

Example 3: API Documentation for a Social Media Application

Context

A social media application is launching an API that allows developers to interact with user profiles, posts, and comments. The goal is to provide clear, concise documentation that facilitates third-party integrations.

With Stoplight, the team can create a visually appealing and informative documentation site.

## Social Media API Documentation

openapi: 3.0.0
info:
  title: Social Media API
  description: API for interacting with social media functionalities.
  version: 1.0.0
servers:

  - url: https://api.socialmedia.com/v1

paths:
  /users/{userId}:
    get:
      summary: Get User Profile
      parameters:

        - in: path
          name: userId
          required: true
          description: ID of the user
          schema:
            type: string
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  followersCount:
                    type: integer
  /posts:
    post:
      summary: Create New Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                content:
                  type: string
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  postId:
                    type: string

Notes

  • This example highlights path parameters and request bodies, crucial for REST API documentation.
  • Stoplight’s collaboration features allow teams to gather feedback on documentation from stakeholders effectively.