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 x-amples, and all but made it compulsory.  The x-amples 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 x-amples stanza is a DSL for writing tests, and service-checker is the test runner.

Not only is this reinvention of the wheel too simplistic for anything more than the most basic testing, it also provides no means of parameterizing runtime values, once again tightly coupling definition and configuration.

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 problem we're trying to solve is documentation, then we should solve for documentation. There are likely many ways of approaching this, but even if we decide that Swagger UI is The Way, we can do so by treating OpenAPI as no more than a DSL for writing docs. Maintainers can manage snippets relative to the endpoints their APIs implement, and a code-generated specification can be put together elsewhere for purposes of driving interactive documentation at the portal.

We should not be publishing OpenAPI specifications or requiring them for every service, there is no innate value in doing so.