OpenAPI Best Practices: operationId, Tags, Enums, Pagination

OpenAPI best practices for a spec that SDK generators, docs, AI agents and n8n node builders can all use: operationId, summary, tags, required and enum, securitySchemes, pagination, and error responses.

Launch your n8n integration - NativeShip.io

In this video:

  • operationId: why it’s a name, and why renaming it is a breaking change
  • summary vs description, and how to write each
  • tags as resources, and why one tag per operation
  • required, enum, format, and examples on your fields
  • securitySchemes for API keys, bearer tokens, and OAuth2 scopes
  • Pagination: what OpenAPI can’t describe, and what to do instead
  • Error responses, and linting with Spectral or Redocly

Chapters
0:00 Same API, two specs
0:37 operationId is a name
1:13 summary vs description
1:44 tags are your resources
2:12 required, enum, format, examples
2:59 securitySchemes: say how to log in
3:33 Pagination, the gap in OpenAPI
4:19 Error responses and linting
4:49 Recap

See what a spec becomes when you build the integration by hand: a 10-part series that takes one API to a verified n8n community node: https://www.youtube.com/playlist?list=PLYkThRYZ5f5g