OpenAPI Sample Library: Complete Project Workflow

💼Project Overview

Project Link - https://github.com/trivedi-khushi/openapi-sample-library/

The OpenAPI Sample Library is a modular and extensive documentation project designed to simplify interaction with various APIs (GitHub, Jira, Notion, Slack, and Stripe). The project utilizes the latest OpenAPI 3.0 specification and serves as a combination of hands-on technical documentation with developer experience (DevEx). Reposiorty Link

This project brings together real-world API Endpoints from 5 widely-used developer platforms, each with different use cases. OpenAPI Sample Library showcases how to write, structure, test, lint, debug, and publish OpenAPI specs in a scalable and professional way.

Intended Audience - Developer, Technical Writers, Project Managers, Developer Advocates (DevRel), Open-Source Contributors.

🎯Goals & Objectives

OpenAPI Sample Library is an interactive API documentation project to make it accessible for developers to test APIs in a zero-setup playground. These are instant, ready-to-use, descriptive, browser-based, supported with copy-paste commands, and even sample values.

The purpose doesn’t compromise on intricacies like easy-navigation, and consistent formatting. The intended outcome is to turn passive documentation into an active tool for developers.

🛠️Project Specifications & Toolchain

🏗️ Project Structure

For ease of maintenance, modularity, and following the standard to draft OpenAPI Documentation for RESTful APIs, the project is managed in a descriptive structure. This structure employs a direct layout:

👇Must read for an entire understanding of the project!

openapi-sample-library/
├── .github/workflows/     ---> includes GitHub Actions workflows (CI/CD, code checks, etc.)
├── api_catalog/           ---> contains all API endpoints based-on org
├── apis/                  ---> contains main OpenAPI specs for each endpoint respective to its org
│   ├── github/
│   ├── jira/
│   ├── notion/
│   ├── slack/
│   └── stripe/
├── components/            ---> includes API components like parameters & schemas for each org
│   ├── github/
│   │   ├── parameters/
│   │   └── schemas/
│   ├── jira/
│   └── ...
├── examples/               ---> YAML file to state sample request/response payloads for each API endpoint
├── images/                 ---> project's media files mainly images.
├── .gitattributes          ---> enforce consistent line endings & text file normalization
├── .gitignore              ---> Ignores generated/local dev files for git not to track them.
├── Dockerfile              ---> Docker setup to preview docs locally via Swagger UI
├── LICENSE  
├── README.md                 ---> about/project description/setup/troubleshooting.
├── about-the-project.mdx     ---> design decisions for the project
├── apis-to-document.mdx      ---> list of API endpoints to documented.
├── getting-started.mdx       ---> Quickstart guide for contributors/new users. [Recommended to reaed]
├── index.html                ---> CStatic Landing Page 

└── openapi.yaml              ---> Root OpenAPI file containing global declarations, (all files are directly/indirectly linked to this)

🛍️Deciding Which APIs to Include?

The project initially (currently) focuses on demonstrating 20 APIs across various Dev tools and services. Following factors were considered for choosing the APIs to demonstrate for the OpenAPI Sample Library:

• Reflect common developer workflows.

• Variety inclusion in case of task use-cases.

• Broad coverage—no repetitive APIs.

• Popular & Familiar APIs from each major platform.

• Covers CRUD operations clearly.

• Rich examples and clearly defined schema.

🌱 Step-by-Step Workflow

Here’s an easy & visual representation of this project’s workflow.

Step-1: Initial Planning & API Research

After deciding on the target APIs and collecting the respective endpoints. For instance, here is an API endpoint for GitHub’s Update an Issue API as :

PATCH /repos/{owner}/{repo}/issues/{issue_number}

To document and implement an API endpoint, you must gather these key details from its official documentation, like:

1. Endpoint URL and Methods (HTTPS, & Authentication)

2. Parameters (body, query, request)

3. Schema definitions- requests & responses

4. All the possible response-codes & error-codes

5. Note the required fields specifically

Step-2: Plan & Design a Modular Project Structure

A repository layout must have a basic structure with a minimum 3 folders: apis/ (endpoint specs), components/ (schemas & parameters) & examples/ (example payloads). Meanwhile, in case of files, maintaining README.md, .gitignore and .gitattribute is considered to be a healthy practice while working on a project or operating a repository.

What Does “Modular” Mean? Why Build a Project This Way?
By modular, it means building your project in independent pieces, and structured so that it becomes easier for reuse & maintenance. It’s just like a toolbox, where the big tools, screws, and wires all live in their own trays within the toolbox.

Hence, a modular project framework makes it easier to:
🔹 Reuse easily,
🔹 Swap or upgrade a single component without disturbing the other
🔹 Quick locating & maintaining.

Step-3: Working on your selected API spec

Writing an API endpoint in OpenAPI Spec is itself a combination of sub-tasks that need to be done carefully. It’s easy with the flow; however, debugging might be a big headache in case of tiny errors like character mismatch or wrong indentation. Make sure you’ve followed the steps carefully so far.

Here’s a table to well define each sub-task for writing an API spec.

Step-4: Linting and Validating the Specification

• Why do we lint our docs?

Linting helps with OpenAPI compliance and reports missing fields/schema/example/mismatches, which are required for the API to work. Linting could be done via various tools, and could even be customized with styles and rules to serve your documentation purposes.

• Set up & Run Redocly CLI:

Install Redocly globally. Make this one-line install npm install -g @redocly/cli command for all OS. Once installed, use the tool for linting and validation within the terminal as: redocly lint openapi.yaml.

• Fixing errors after the Linting tool reports them

You’ll first need to understand the structure of the error message. Each comes with an exact error-statement, line number, file name, and a description/hint for fixing it.
Your next step would be opening that dedicated file, and its line number to find the error, then making suitable change(s) to fix it. Save your changes, and re-run the command to check. Repeat this cycle until you find 0 warnings.

Here’s how linting tools (here Redocly) report errors & validation:

Step-5: Setting Up Local Preview with Docker + Swagger UI

• Declaring a Dockerfile:

Use the swaggerapi/swagger-ui image create with docker dektop and copy in your OpenAPI spec. This will be configured as the entry point.

Build & Run

bashCopyEdit# 1 – Build the image once (re‑run when Dockerfile or YAML changes)
docker build -t api-docs:latest .

# 2 – Launch Swagger‑UI, mapping container port 8080 → host port 8080
docker run --rm -p 8080:8080 api-docs:latest

Access: open http://localhost:8080 to view the interactive docs and “Try it out” console.

Step-6: Generalizing & Repeating the Process for Other APIs

Repeat the above steps for another API that you’d like to work on. It’s that simple!

Maintaining such a uniform workflow is a professional practice to have consistency, easy maintenance, and scalability in the project.

👥Contribution Guidelines

The following steps answer the question which most beginner contributors might be worried about- “How can collaborators work on this repository?”

Step-1: Fork this repository- https://github.com/trivedi-khushi/openapi-sample-library

Step-2: Create a dedicated Git branch and name it to clearly reflect the specific change you’re working on (e.g., feature/stripe‑api-add or fix/schema‑typo).

Step-3: Follow the structure, guidelines, and flow so far. Work on your contribution.

Step-4: Use tools to validate & test your changes.

Step-5: Push your changes to the dedicated branch of your forked repository.

Step-6: Go to the main repository. Open a Pull Request (PR) and make it something like main-branch ← “your-branch-name”

Step-7: Add a valid message & description, and submit a Merge Request(MR) for the same, after the checks are passed.

Step-8: Automated checks will pass before submitting your MR. Here’s what to do in each case:

• All checks pass (green)→ PR gets submitted to the reviewer.

• Something fails (red) → review the logs, fix, and push again.

🏋️‍♀️Challenges Faced

Here are tabular pointers to list the Blockers faced while working on the project, with an explanation of the issue-faced and how were they tackled.

If you face a new issue while contributing to this project, or working on a similar one, the reach out to me for assistance.

FAQs