Skip to content

README.md

Latest commit

 

History

History
173 lines (115 loc) · 3.88 KB

README.md

File metadata and controls

173 lines (115 loc) · 3.88 KB
Raw

OpenAPI Workshop

This standalone project is a practical developer workshop for learning OpenAPI through a simple Product Catalog API. It focuses on one contract file, one mock workflow, and one recommended client-generation flow so developers can get started quickly.

Audience

  • Frontend developers
  • Backend developers
  • Full-stack developers
  • API consumers and integrators
  • QA engineers working with APIs

Workshop Purpose

The workshop teaches contract-first API development using the sample contract at:

openapi-workshop/contracts/product-catalog-api.yaml

Participants learn how to:

  • read an OpenAPI contract confidently
  • validate schemas and error responses
  • run a mock API before backend implementation exists
  • generate a typed client from the same contract
  • make small safe updates to the contract

Prerequisites

  • Node.js 18+ and npm
  • Java Runtime Environment if using openapi-generator-cli
  • Terminal access
  • Optional: curl

Folder Structure

openapi-workshop/
├── contracts/
│   └── product-catalog-api.yaml
├── labs/
├── solutions/
├── openapi-workshop.md
├── workshop-guide.md
└── exercises.md

openapi-frontend-contract/
├── openapi-frontend-contract.md
├── openapi-frontend-contract.pptx
└── artifact-build-manifest.json

Setup

From the repo root:

npm install

This installs the workshop CLI tools locally and enables the npm scripts below.

Run Prism Mock Server

From the repo root:

npm run mock

Direct command:

prism mock openapi-workshop/contracts/product-catalog-api.yaml

Expected result:

  • Prism starts successfully
  • The mock server is available on http://localhost:4010

Validate The OpenAPI Contract

From the repo root:

npm run validate

Expected result:

  • Validation completes successfully with no schema errors

Run Code Generation

Generate the recommended TypeScript fetch client:

npm run generate:client

This workshop intentionally uses one primary generator target so the flow stays simple. Teams can try other generators later using the same contract.

Available Scripts

From the repo root:

npm run mock
npm run validate
npm run generate:client
npm run verify

What they do:

  • mock starts Prism against the workshop contract
  • validate validates the OpenAPI contract
  • generate:client generates the recommended TypeScript fetch client
  • verify runs validation and client generation

Use The Solutions Folder

The worked solutions live in:

  • openapi-workshop/solutions/lab-01-openapi-basics-solution.md
  • openapi-workshop/solutions/lab-02-contract-review-solution.md
  • openapi-workshop/solutions/lab-03-prism-mock-server-solution.md
  • openapi-workshop/solutions/lab-04-client-generation-solution.md
  • openapi-workshop/solutions/challenge-lab-solution.md

Use these after the hands-on lab, during debrief, or when preparing to facilitate the workshop. The challenge solution is optional.

Troubleshooting

Prism command not found

Use:

npm run mock

OpenAPI Generator command not found

Use:

npm install

Or run the generator directly after install:

npx openapi-generator-cli version

Validation fails

Check for:

  • incorrect indentation in YAML
  • broken $ref pointers
  • missing required arrays
  • invalid enum values
  • invalid schema keywords for the declared type

Generated client output is large

This is normal. Generated clients include models, API classes, helpers, and configuration. Treat the generated code as reproducible output and wrap it with thin adapters if your application needs custom behavior.

Contract filename confusion

OpenAPI does not require a specific filename such as openapi.yaml. This workshop intentionally uses product-catalog-api.yaml so the teaching story stays consistent across slides, labs, and demos.