24 ms·
I like artifact-driven API design. If you must use REST, Swagger is a pretty decent way to get your API fully set up with everything but the business logic. Per
by languagehacker 5y ago
I like artifact-driven API design. If you must use REST, Swagger is a pretty decent way to get your API fully set up with everything but the business logic. Personally, I love GraphQL's Schema Definition Language. The whole thing is designed to explicitly declare data types and how to query for and operate on them, we with plenty of room for building documentation in along the way. Sadly, many popular implementations don't start with the SDL, but an SDL can be generated through those, and the good ones are smart enough to pull in documentation from code comments or addordances in their DSL.
- dpritchett 5y agoAgreed! I like grpc for the same reason. If I need to work with REST, a schema-first approach is ideal as it means various client, server, validation, and documentation dimensions are in sync by default. I get why folks often come at it from the other end and just layer some swagger annotations on top of their existing server code — lack of experience, the dynamicist’s mistrust of typing in general, or maybe they’re in a niche stack without a workable binding generator. Still, it’s better for everyone if the API provider can pull off the artifact-driven approach.
- legutierr 5y agoAre you aware of anything like Swagger or SDL but for JSON RPC? I've been looking, but haven't come across anything that can generate documentation from code, or generate code from documentation, the way that you can with Swagger.