Hacker News new | past | comments | ask | show | jobs | submit login

I understand more than a few do this and love this. To me the schema & design should test the implementation. If you generate the schema based on the implementation, your schema is basically implicit.

I dont think by doing it this way you really get the benefit of the premise of this article. You get some other benefits, like API documenation and perhaps client code generation and that's perfectly ok if that's all you need.

However, if you believe in the idea of schema-driven, design-first api development, don't do this.




I think the parent comment doesn't mean that the schema is generated from the implementation, but that there are annotations colocated with the code that provide metadata to generate the schema.

This is what I do. I have typescript functions that generate openapi responses.

I do generate the schémas from sequelize models, blending in descriptions and enums where appropriate.

https://southpole.stoplight.io/docs/calculate/docs/CSV%20imp...


We first write the OpenAPI spec in collaboration with non-developer stakeholders (product managers or whatever).

Then we write the code to implement the spec. (We tried using code generators for this step, but quickly dropped them. If your language and web frameworks are sufficiently concise, adapting the generated code to your needs is likely to be more work than just writing from scratch.)

Then we enable an automatic tool to automatically generate an OpenAPI spec from the code. We can then compare it to the original spec to quickly see if we missed something. It's not an automated diff, but it still saves a _ton_ of time.

Finally, we use code generators for the client code. Those actually work pretty well, unlike server-side code generators, probably because there's little room for customisation in making HTTP requests.




Consider applying for YC's W25 batch! Applications are open till Nov 12.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: