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