We use Swagger at work with compojure-api, and it’s pretty fantastic. It provides an automated process for generating a service test page that you can give to people developing the client. It also ensures that a bit of structure is added around the routing making it easier to maintain long term.
i use swagger with akka-http using annotations to automatically generate the swagger doc from the scala source code. mostly works pretty well, but occasionally the scala data structures gets mangled in translation, which is pretty annoying. but then i recall what i did before, which was manually documenting stuff or worse, nothing at all.
Author is concerned mostly about Java tools (client code generation, specification generation from annotations) and lack of “hypermedia” support. Hypermedia is not a big deal, is there any real-world API that uses this approach?
Lack of forward compatibility, though, might be a problem with OpenAPI itself. API specifications in it describe only current version of protocol and you can’t define forward compatibility rules, such as “if enum has other value, treat it as this value”. At least “object” keys are non-required by default, just like in json schema, this enables forward compatibility. The problem might be not only with enums, but with anyOf/oneOf, which can be treated as generalization of enums (sum types).
For “robustness principle” to work, API specification should enable writer to be conservative (i.e. don’t allow non-listed values in enums) and readers to be liberal (i.e. substitute default values for unknown enum values). This is not supported by OpenAPI.
I don’t understand this argument at all. Swagger is a tool for generating API documentation. Client generation is afterthought, it’s documentation tool primarily.
We’re considering introducing this in at work, because apparently maintaining docs and client libs is too difficult for today’s engineers. Am curious what other lobsters have had as experiences.
My experiences have been pretty positive. At the very least, it’s way better than what most organizations use instead (i.e. nothing).
My first time using it, I was grafting it onto an existing API and was pleasantly surprised to see that it was expressive enough to bend to the existing functionality. All the stuff it enables is great – automated conformance testing being the big one, in my book.
Have you thought about gRPC, or twirp at all? If the use-case is internal-facing systems then I think what a lot of people really want is RPC. Swagger seems great for external-facing systems, though.
(Disclaimer: I haven’t used any of the tools I just mentioned :D)
We have also used it quite a bit at work, getting the most benefit from automatic documentation of endpoints. The automatic client lib generation didn’t work very well for us, and hand written clients were our approach.
Depending on what your API is written in, you may have quite good support for generating pretty detailed docs.
Also, this opens the door for some kind of automated testing against the API, based on the Swagger definition, but, I never got around to doing that.
We use Swagger at work with compojure-api, and it’s pretty fantastic. It provides an automated process for generating a service test page that you can give to people developing the client. It also ensures that a bit of structure is added around the routing making it easier to maintain long term.
i use swagger with akka-http using annotations to automatically generate the swagger doc from the scala source code. mostly works pretty well, but occasionally the scala data structures gets mangled in translation, which is pretty annoying. but then i recall what i did before, which was manually documenting stuff or worse, nothing at all.
Author is concerned mostly about Java tools (client code generation, specification generation from annotations) and lack of “hypermedia” support. Hypermedia is not a big deal, is there any real-world API that uses this approach?
Lack of forward compatibility, though, might be a problem with OpenAPI itself. API specifications in it describe only current version of protocol and you can’t define forward compatibility rules, such as “if enum has other value, treat it as this value”. At least “object” keys are non-required by default, just like in json schema, this enables forward compatibility. The problem might be not only with enums, but with
anyOf/oneOf, which can be treated as generalization of enums (sum types).For “robustness principle” to work, API specification should enable writer to be conservative (i.e. don’t allow non-listed values in enums) and readers to be liberal (i.e. substitute default values for unknown enum values). This is not supported by OpenAPI.
Note that “new XSD” is json schema and not Swagger/OpenAPI (OpenAPI uses some subsets of json schema in its format). YAML is used only as syntax sugar over json, primary data model of all this is json.
I don’t understand this argument at all. Swagger is a tool for generating API documentation. Client generation is afterthought, it’s documentation tool primarily.
Github’s REST API uses hypermedia extensively, in the various “*_url” properties and RFC 6570 URI template values.
We’re considering introducing this in at work, because apparently maintaining docs and client libs is too difficult for today’s engineers. Am curious what other lobsters have had as experiences.
My experiences have been pretty positive. At the very least, it’s way better than what most organizations use instead (i.e. nothing).
My first time using it, I was grafting it onto an existing API and was pleasantly surprised to see that it was expressive enough to bend to the existing functionality. All the stuff it enables is great – automated conformance testing being the big one, in my book.
Ah, neat. I already had been running boring documentation and updates (wiki ops, wheee), and am resistant to change if something works.
But, if it’s been working well for other folks, it’s worth investigating.
Have you thought about gRPC, or twirp at all? If the use-case is internal-facing systems then I think what a lot of people really want is RPC. Swagger seems great for external-facing systems, though.
(Disclaimer: I haven’t used any of the tools I just mentioned :D)
We have also used it quite a bit at work, getting the most benefit from automatic documentation of endpoints. The automatic client lib generation didn’t work very well for us, and hand written clients were our approach.
Depending on what your API is written in, you may have quite good support for generating pretty detailed docs.
Also, this opens the door for some kind of automated testing against the API, based on the Swagger definition, but, I never got around to doing that.
We use https://www.apibuilder.io/