We have created a API docs engine as part of the platform development. The input can be RAML or OAS files and the result is stripe style 3 column API docs with generated code examples for each endpoint and method for selected programming languages. The last part of it is expanding now to support more and more programming languages. The engine also runs the generated code examples against the API by default. Thus we can assure that give code examples actually work. Otherwise the build does not pass and is not pushed to production.

Yes, the Responses section in the middle is losing information at the moment, but fix is coming. The reason is that we need to convert in this version RAML to OAS first and then do the rest. In the coming version we mostly rely on OAS format since that is the current default.

Pile of invalid OpenAPI spec files

As part of testing various Open API specs available in the web as feed for our API docs engine we have found out that a lot of them are not even valid….This was a shock to me. I would expect companies to validate the spec files before pushing public. What can you do with invalid spec files?

For this purpose we have to add extra configuration option to the engine (which is going to sold as a service beginning next year). Option is strict or not. If strict is on, then we require valid input, if not, then we take what is given and hope for best possible result. Reasoning is that if the customers don’t have valid spec files, they won’t be able to see our tool in action at all.

We do recognize that the result is not optimal and some of the customers will get bad impression of the tool because of this. We need to make a selection:

Which of the options does in your opinion work better in selling the solution?

Killing developer tool usage with your API

I’m not sure if for example Postman “eats” invalid spec files but at least it does validate the input and report errors. No, it does not. I just tested it and result from reading in Sendgrid’s massive OAS file available at Github resulted to error and nothing was imported

Putting out invalid spec files prevents your customers to take advantage of those. They are not able to import the files to their tools. Postman is just one example. I would expect other tools to require valid files as well. Bad customer and developer experience is probably not your intention.

Respect your customers and provide valid spec files

Perhaps the vendors should add simple validation step in the CI/CD process before pushing the specs out. Of course there might be multiple reasons for invalid spec files, but I guess some portion of them are result of code-first approach. If the process is design-first then the validation should catch the invalid parts already there before implementation. Of course design-first approach does not guarantee that design is used in the implementation or testing. It’s hard to say why so many invalid specs are published.

Some more to read from 100 Days DX