Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 37 ยท Projects and Practice

Practice: Review a Flawed OpenAPI Document

Practice reviewing an OpenAPI document: find ten planted mistakes, check your list against a runnable reviewer, use a tooling cheat sheet and test yourself with a mixed quiz.

Reading specs critically is a skill, and it improves with practice. This final lesson gives you a flawed document to review, a reviewer script that checks your findings, a cheat sheet of the tools in this chapter group, and a mixed quiz that touches code generation, documentation, validation and design-first workflows.

Nothing here needs the real tools: the YAML is read-only, and the reviewer is a Python stand-in.

Exercise 1: find the mistakes

Read this document carefully before running anything. It contains ten problems of the kinds covered in this part of the course.

YAML
openapi: 3.1.0
info:
  title: Library API
paths:
  /getBooks:
    get:
      tags: [books]
      parameters:
        - name: limit
          in: query
          schema: {type: string}
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: array
                items: {$ref: "#/components/schemas/Book"}
  /books/{id}:
    get:
      operationId: getBook
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Book"}
    delete:
      operationId: getBook
      summary: Remove a book
      responses:
        "204":
          description: gone
components:
  schemas:
    Book:
      type: object
      properties:
        title: {type: string}
        page_count: {type: integer}
        price: {type: number}

Write down your list, then compare with the reviewer below.

Exercise 2: run the reviewer

The stand-in reviewer encodes ten checks. It loads the same document (as JSON) and reports every finding with a short category label. Compare its list with yours; for anything you missed, read the check and ask why it matters.

Python Stand-in: automated reviewer for the flawed document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The reviewer finds more than ten lines because several planted problems show up in more than one place. Which ones depend on opinion? For example, a missing 404 is a design choice the style guide should settle.

Exercise 3: fix and re-check

Rewrite the YAML so the reviewer's list is empty. Good fixes include a version and description, a noun path (/books), declared as a path parameter, an integer limit, unique operationId values (deleteBook), required: [title, price], camelCase properties (pageCount) and real response descriptions. Then add what no simple script checks for you: examples, error schemas and security.

Tooling cheat sheet

Goal Tool Command or idea
Lint style and quality Spectral spectral lint openapi.yaml
Interactive docs Swagger UI SwaggerUIBundle({url, dom_id})
Static reference docs Redocly CLI redocly build-docs openapi.yaml
Generate SDK or server OpenAPI Generator generate -i spec -g python -o out
Mock server Prism prism mock openapi.yaml
Request/response validation validator library or Prism proxy check both directions at runtime
Contract tests Schemathesis, Dredd, Pact generated inputs, spec examples, consumer pacts
Breaking-change check oasdiff oasdiff breaking old.yaml new.yaml
Split and bundle Redocly CLI redocly bundle, redocly split

Exercise 4: mixed quiz

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You regenerate your TypeScript SDK and every method name changed. What is the most likely cause?

    Generators name methods from operationId. Changing or omitting it changes the generated API.
  2. 2. Try it out in Swagger UI fails in the browser but curl succeeds. What do you check first?

    Browser requests obey CORS; curl does not.
  3. 3. A new required query parameter is added to an existing operation. How does a diff tool classify it?

    Old clients do not send it, so their requests fail.
  4. 4. Which approach finds a 500 error at the boundary of a numeric parameter that nobody wrote a test for?

    It generates boundary and invalid inputs from the schema automatically.
  5. 5. Why publish a bundled spec instead of the multi-file root document?

    The bundle is self-contained and works for every consumer.

Where to go from here

You now have the whole workflow: design a contract, lint it, document it, mock it, generate code from it, test the running API against it, and keep it compatible as it grows. Pick a real API you use and write its OpenAPI document from its behavior, then run the checks from this chapter group with the real tools on your own machine.

Summary

  • Reviewing a spec is a checklist skill: metadata, naming, IDs, types, errors, descriptions and schemas.
  • A reviewer script catches mechanical problems; humans judge design.
  • Each tool has one job: lint, document, generate, mock, validate, test, diff, bundle.
  • Keep the spec in version control and enforce it in CI.
  • The Python reviewer is a stand-in for linters and validators.

Next: Back to the OpenAPI and Swagger course