Why I don't like generating API specs

Last week, I talked about how to get started writing an API specification. I had several people reply and ask about tools which automatically generate an API specification from your code.

For example, in the Laravel world, there is Scramble or Laravel Open API. Both packages have the same basic premise: they will look at your code and automatically generate the API spec from it, whether via attributes you manually specify or through static analysis.

This sounds great! Instead of writing YAML by hand (like I do), or even using a fancier desktop tool for authoring the spec, just let the package do it from the code you already wrote.

There are two basic reasons that I personally don't like this approach:

First, I've yet to see a tool that can actually generate a spec as completely as I would write it. Either some specific property I want to set is missing, or it generates it in a way I find confusing. And I've yet to see one that leverages the full power of the OpenAPI spec, such as using references.

Second, and this is by far my biggest reason, I don't like the idea of an API spec being updated automatically just because I changed some code. One of the things I value most in having a specification is that it's a clear contract of what the API should do. Any changes to it should be deliberate and coordinated so as not to break that contract.

You could rely on a code review process to catch unintentional changes to the spec, but that still doesn't sit right with me. It feels a bit like auto-generating test logic from application code. I'd lose confidence that it's actually providing the value I want.

Here to help,

Joel

P.S. I'd love to have you join the Mastering Laravel community. Check out the link for more information on how to join.