User:EEvans (WMF)/Opinions/OpenAPI

= OpenAPI Considered Harmful = From Wikipedia:"The OpenAPI Specification, previously known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Swagger and some other tools can generate code, documentation and test cases given an interface file."

Hot or not?
A machine readable specification would seem to offer many benefits, but how many of them are manifest? Production and consumption are oft-cited, but who among us has used a spec to generate client or server stubs, and of what value would they provide once the stub has been filled in? If you cannot either generate the specification from code, or (meaningfully) generate code from the specification, then the specification becomes a (manually maintained) duplication.

Of the benefits cited, the only compelling one is documentation.

On separation of concerns
Of the information encoded in a valid specification, some of it directly correlates to the interface, and some of it to the instance of the service implementing that interface. The former moves in lock-step with the code (it is code for all intents and purposes), but the latter is configuration. This coupling violates well established separation of concerns (you would never hard-code contact information, port numbers, or filesystem paths in application code).

This isn’t just a hypothetical concern, consider RESTBase, where the inability to maintain this separation resulted in the specification becoming the application configuration.

Making it worse
Here at the Foundation, we’ve created an extension called, and all but made it compulsory. The  structure is added on a per resource and method basis, and describes a valid request and the expected response. A script called service-checker is executed against a published specification, invokes the service using the request defined, and validates a compliant response. We use this for availability monitoring. This sounds great, but all we’ve really done is implement a bespoke way of doing integration testing; The  stanza is a DSL for writing tests, and service-checker is the test runner.

Additionally, not only is this bespoke integration testing too simplistic for anything more than the most basic of synthetic transactions, it also provides no means of parameterizing runtime values, once again requiring that we hard-code configuration into the specification.

Conclusion
OpenAPI isn’t an original idea, WSDL (for example) flashed in the pan more than 20 years ago. Unlike OpenAPI, the SOAP frameworks of the day were able to generate WSDL output. However, even without OpenAPI's issues, WSDL ultimately failed because it wasn't compelling; WSDL failed because it was a solution in search of a problem, and so is OpenAPI.

If the Swagger UI is really how we want to do documentation, we can do so by treating OpenAPI YAML as the DSL we use for writing docs. Maintainers can manage snippets relative to the endpoints their APIs implement, and a code-generated specification can be put together for purposes of driving interactive documentation at the portal.

We should not be publishing OpenAPI specifications, there is no innate value in doing so.