Bump.sh

Writing an OpenAPI Document from the Ground Up

Composing an OpenAPI document can be daunting, especially during the early stages of API design. Your API design will need to evolve as you learn more about the problem space. To avoid needing to re-write large portions of your OpenAPI document, I recommend a phased approach to designing and documenting your API. The process starts with a breadth-first approach, capturing the essentials of the API including purpose and scope, then adding high-level operational descriptions. Finally, add more detail as you gain insights and receive feedback, until your OpenAPI document is complete.

In this article, we will break the OpenAPI documentation process into three phases, with steps within each phase to help you get the most out of your document. Each phase will keep your OpenAPI document syntactically valid for input to your tool chain. To see the process in action, we will use an example TODO list API to show how you can iteratively produce your OpenAPI document as you gain a deeper understanding of the needs of your developers.

Introducing the TODO API #

To understand the phased approach, let’s use a simple TODO API example. The API will support the following operations:

  • Add a new task - POST /tasks
  • View a task - GET /tasks/{taskId}
  • Update a task - PUT /tasks/{taskId}
  • Delete a task - DELETE /tasks/{taskId}
  • List tasks - GET /tasks

While we could add more operations, this API will provide a good sample of operations to better understand how to iteratively compose our OpenAPI documentation. Let’s get started by first capturing the info section.

If you are new to the OpenAPI Specification, check out our article titled, “What is OpenAPI?” to gain better understanding prior to jumping into this step-by-step guide.

Looking for an OpenAPI reference? Be sure to check out the OpenAPI Cheat Sheet.

Phase 1: Create the Info Section #

The info block is crucial as it contains essential metadata about your API, including the title, description, version, and terms of service. It helps readers quickly understand what your API does and the terms associated with its use.

Step 1.1: Define the API Title #

  • Objective: Create a descriptive and succinct title that is SEO-friendly.
  • Guidelines:
    • Be descriptive enough so that the reader immediately understands what the API offers.
    • Avoid generic and vague terms like ‘service’, ‘manager’, and ‘controller’, which do not provide insight into the API’s functionality and leaks implementation details.
  • Actions:
    • Create the boilerplate of the document, including openapi and info sections
    • Add a thoughtful title using the guidelines above

Example:

openapi: 3.0.0
info:
  title: Personal TODO List API
  version: 1.0.0

Step 1.2: Write a Compelling API Description #

  • Objective: Offer a clear summary of what the API does, its scope, and capabilities.
  • Actions: Add a description of the API
  • Tips:
    • Include purpose and scope to clarify the API’s intent.
    • Mention key digital capabilities to outline what the API can do.
    • Highlight the workflow or typical use cases to guide the reader on how to implement the API effectively.
    • Utilize Markdown for formatting to enhance readability and structure of the content.

Example:

openapi: 3.0.0
info:
  title: Personal TODO List API
  version: 1.0.0
  description: 
    This API allows an individual to manage a simple list of tasks. 
    
    Tasks have a status of 'new' when first created and should be moved to 'in progress' when the task has begun and 'completed' once the task is finished.

Step 1.3: Include Additional Metadata #

  • Objective: Add additional metadata and a boilerplate section to ensure the document is syntactically valid.
  • Actions: Add the following sections:
    • Contact Details: Add relevant contact information like an email, phone number, or a link to your API support or contact page.
    • Licensing Details: Specify the API’s license type and include a link to the full license text if available.
    • Version: Note the current version of the API document, which is important for users to track changes and updates.
    • Servers: If you know the URL(s) for your servers, go ahead and put them here. Otherwise, you can add them later.
    • Paths: Since we focused on the info section for now, let’s create an empty paths section to ensure the file will validate without any errors.

Example:

openapi: 3.0.0
info:
  title: Personal TODO List API
  version: 1.0.0
  description: 
    This API allows an individual to manage a simple list of tasks. 
    
    Tasks have a status of 'new' when first created and should be moved to 'in progress' when the task has begun and 'completed' once the task is finished.
  contact:
    email: api-support@todolist.local
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://onlinestore.com/terms    
paths: {}

Step 1.4: Review and Revise #

  • Objective: Ensure clarity, accuracy, and effectiveness of the information provided.
  • Action: Review the info section with stakeholders, revise based on feedback, and keep it updated as changes occur in services or terms. Validate that the OpenAPI document is valid using your favorite editor or the Swagger Editor as a quick check.

For more information on improving your info section, refer to the article titled, “Enriching Your OpenAPI Info Documentation for Understanding”

Phase 2: Capture High-Level Operation Details #

Next, let’s capture some basic operation details. This will include the paths and HTTP methods our API will offer, along with some summary and description details. We will expand the operations further in the final phase. For now, focus on identifying all of the operations you will need to capture.

You may be thinking that the next step is to capture schema components. However, I’ve found that taking a breadth-based approach to the operations first offers a better opportunity to identify all necessary schema components without getting too deep too quickly.

Step 2.1: Capture Paths and HTTP Methods #

  • Objective: Capture the basic framework of API operations before adding details.
  • Action: Focus on capturing all API operations using only the paths and HTTP methods. Additional details will be added later.
  • Guidelines:
    • Each operation is specified under the paths object in the OAS.
    • Operations are defined by HTTP methods like GET, POST, PUT, PATCH, DELETE, etc.

Example:

paths:
  /tasks:
    get:
    post:
  /tasks/{taskId}:
    get:
    delete:
    put:

Step 2.2: Capture Operation Summaries and Descriptions #

  • Objective: Document the purpose and details of each API operation.
  • Actions:
    • Write a short summary about the purpose of each operation, along with a more detailed description.
    • Add an operationId to provide a unique name to each operation which can be useful for linking and clarity.
  • Tips:
    • The summary of each operation will be the first thing the reader sees, so spend time crafting a thoughtful summary.
    • The description should provide further context on when (and when not) to use the specific operation to give the reader confidence that they are in the right place.
    • Utilize Markdown for formatting the descriptions to include bold, italics, bullet points, and links.
    • Be descriptive and avoid generic phrases; provide enough context to understand the operation’s utility and execution.

Example: