This is a little side topic but one of my greatest issues with swagger is that it's often providing api documentation after the fact and is difficult to trace through a version control system to understand the changes to an API over time. This is due to what I feel is swaggers complexity as a json spec and our desire to define the spec in code (either through annotation based processors in Java or data maps on compojure).

I like defining a graphql specification in a .schema file or .edn file and handling resolvers or the implementation separately to the specification.

I also get this in grpc protobuf specifications.

Do I ask too much out of my restful specification?

@jeremy not exactly what you ask, but you can also save the swagger files under version control and use tools like swagger-diff to get the actual changes between versions.

@ikitommi Thanks. I will probably spend some time re-evaluating swagger. We use it for all of our services, but only as an after the fact auto-generated specification documentation in annotated Java code. Once you move to writing the specification in the json file, there is no adherence to the specification required like you would get with graphql schemas or grpc. But maybe I could resolve my issues by getting back up to date with the supporting tools around swagger and reevaluating our api change process.