2 ms·

I'm for swagger but only if the router uses it. I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`. Vertx web

I'm for swagger but only if the router uses it. I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`. Vertx web api contract router. Which takes in a swagger file, and routes based on the `swagger` operation id. Is the closet I've seen. https://vertx.io/docs/vertx-web-api-contract/kotlin https://vertx.io/docs/vertx-web-api-contract/kotlin I've also written a library to route into ktor in a type safe way. But if you're doing swagger. To me it should be written, then consumed by the back-end service. Then generate front-end clients. Anything less will result in bugs. I've seen companies pile on so many services. To double check code generated swagger. Hit a bug, then have to maintain the swagger spec outside and not enforce it.

pibi 7y ago
That's my mantra since 5 years now. Swaggerize-express or swole for the routing, but also swaggering-mongoose or objection's schema loaded from the yaml file for the database model. As a plus, validation is available out of the box. less code, standard approach, less bugs.
eropple 7y ago
> To me it should be written, then consumed by the back-end service. This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it. I've written a couple of libraries that do exactly this: https://github.com/eropple/nestjs-openapi3 https://github.com/eropple/nestjs-openapi3 - OpenAPI3 library for NestJS that standardizes input validation https://github.com/modern-project/modern-ruby https://github.com/modern-project/modern-ruby - a Ruby web framework built around OAS3 concepts + rigorous validation

pibi 7y ago

That's my mantra since 5 years now. Swaggerize-express or swole for the routing, but also swaggering-mongoose or objection's schema loaded from the yaml file for the database model. As a plus, validation is available out of the box. less code, standard approach, less bugs.

eropple 7y ago

> To me it should be written, then consumed by the back-end service. This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it. I've written a couple of libraries that do exactly this: https://github.com/eropple/nestjs-openapi3 https://github.com/eropple/nestjs-openapi3 - OpenAPI3 library for NestJS that standardizes input validation https://github.com/modern-project/modern-ruby https://github.com/modern-project/modern-ruby - a Ruby web framework built around OAS3 concepts + rigorous validation