The case for and against. What OpenAPI does well, and when it costs too much.
For. What works in its favour.
- Open, vendor-agnostic standard (no lock-in).
- Completely free with a rich open-source tool ecosystem.
- Auto-generated documentation and client code.
- Recognized industry-wide across the web.
- Facilitates collaboration between teams and companies.
- Native support for versioning and compatibility.
- You need a common interface between teams (front/back).
- You want to auto-generate client code.
Against. What to plan for.
- Learning curve for the format (JSON/YAML).
- Can be verbose for very simple APIs.
- Requires regular maintenance to stay synced.
- Variable quality and support of third-party tools.
- You prefer manual or informal documentation.
- Your team has no familiarity with the format.
