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

The biggest difference between openapi and soap(/wsdl) that I think openapi more descriptive vs soap being prescriptive. As in openapi is supposed to be able to describe pretty much any sort of api, as long as it is over HTTP. In comparison soap wants you to design your api to fit the soap model. So in that sense I see soap being closer to grpc than openapi.

I'd also echo the sentiment that iterating on good ideas is useful and not always just reinventing the wheel.




Except in practice the only accurate and complete openapi specs I see are generated from code annotations or are used to generate the service code. It’s a particular form of worse is better where overall you end up doing the same work as in the soap/wsdl days if you want to finish the job, but because in the beginning you can just hammer out undocumented code it feels much easier. Regrettably many developers stop at 80% and produce openapi specs that have the appearance of completeness without actually being complete.


My preferred approach is to use the OpenAPI as a spec, i.e. to drive the implementation, rather than just documenting the implementation. I wrote a little Python framework [1] to help me put that approach into practice.

[1] https://pyotr.readthedocs.io




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

Search: