The 15 rules of the OpenAPI-based tools club

By Arnaud Lauret, June 1, 2022

The OpenAPI Specification can facilitate everyone’s life and participate in the creation of better APIs and a better API ecosystem. But it will work only if the members of the OpenAPI-based tools club follow the rules.

Banner by my partner in crime Mister Lapin.

As an OpenAPI-based tool creator and Web API tool creator in general, you have a responsibility to promote the use of the OpenAPI specification, demonstrate how to take advantage of it, and educate the API community. Why? Because you’re a nice person/organization and you want to help everyone create the best possible APIs and API ecosystem. And also because the more significant the API/OpenAPI ecosystem will be, the better it is for your tools and you. Everybody wins in the end.

Well, everybody wins only if you follow the rules of the OpenAPI-based tools club:

1. All Web API tool creators and vendors are de facto members of the OpenAPI-based tools club.
2. All members of the club leverage the OpenAPI Specification in their Web API tools.
3. Use as many features of the OpenAPI Specification (and underlying JSON Schema Specification) as possible in your context.
4. Use OpenAPI extensions only when needed.
5. Support OpenAPI documents JSON and YAML formats.
6. Support multi-file OpenAPI documents that use external references ($ref).
7. Support the latest version of OpenAPI quickly.
8. Support (most used) older versions of OpenAPI.
9. Always put forward the latest version of OpenAPI in documentation, samples, examples.
10. Advertise your tools is taking advantage of OpenAPI.
11. Document what parts of OpenAPI are supported and how they are used, and what is not supported.
12. Don’t say or write “Swagger” in place of “OpenAPI.” Explain the difference to your users and customers when they say “Swagger”.
13. Share your stories in a “how we create amazing features thanks to OpenAPI” mode. Avoid just proposing “What is OpenAPI + clickbait” content.
14. Give feedback, propose ideas, and participate in the OpenAPI community.
15. Talk about the OpenAPI-based tools club as much as possible and share the rules.

Feel overwhelmed? Fear of not being able to follow all the rules? No problem, remember rule #1; as a Web API tool creator, you’re de-facto a lifetime club member. Please do your best and ask for help from OpenAPI and JSON Schema communities to provide the best possible support to the OpenAPI Specification in your tool and the API space; it’s good for you and the community.