# Review an OpenAPI specification

Use this when someone asks you to review, critique or sanity-check an OpenAPI
document before it is published to the marketplace.

## Steps

1. Read the whole document before commenting on any part of it. A path that
   looks wrong in isolation is often correct given a shared parameter or a
   security scheme declared elsewhere.
2. Check that every operation has a summary, an operationId, and at least one
   documented response other than 200. Consumers generate clients from these.
3. Check that error responses reference a shared schema rather than restating
   an ad hoc object per operation.
4. Flag any endpoint that accepts a free-form object with no schema, and any
   that returns one.
5. Check security: every operation either inherits the global security scheme
   or declares its own. An operation with `security: []` is public, and that
   is almost never intended.
6. Report findings grouped by severity, and say plainly which ones block
   publication and which are improvements.

## What not to do

Do not rewrite the specification. Report what is wrong and why it matters to
the person who will consume the API, and leave the authoring to its owner.

---
name: review-an-openapi-specification
description: 'Reviews an OpenAPI document before publication and reports what blocks it, grouped by severity.'
---

# Review an OpenAPI specification

Use this when someone asks you to review, critique or sanity-check an OpenAPI
document before it is published to the marketplace.

## Steps

1. Read the whole document before commenting on any part of it. A path that
   looks wrong in isolation is often correct given a shared parameter or a
   security scheme declared elsewhere.
2. Check that every operation has a summary, an operationId, and at least one
   documented response other than 200. Consumers generate clients from these.
3. Check that error responses reference a shared schema rather than restating
   an ad hoc object per operation.
4. Flag any endpoint that accepts a free-form object with no schema, and any
   that returns one.
5. Check security: every operation either inherits the global security scheme
   or declares its own. An operation with `security: []` is public, and that
   is almost never intended.
6. Report findings grouped by severity, and say plainly which ones block
   publication and which are improvements.

## What not to do

Do not rewrite the specification. Report what is wrong and why it matters to
the person who will consume the API, and leave the authoring to its owner.