The purist position is that a version belongs in the Accept header because a URL identifies a resource rather than a representation, and the practical position disagrees. Both…
Serving the interactive documentation from the application is convenient and publishes a complete map of every endpoint, parameter and error code to anybody who finds the URL. The…
Generating the document is only half of it: committing the generated file is what turns an API change into something a reviewer can see. Sorting with jq -S…
A generated client removes the hand-written HTTP layer and produces a large amount of code nobody has read, in a style nobody chose. For six endpoints a hand-written…
A document describing what the API accepts and a validator enforcing it are two implementations of one rule, and they diverge in the direction of the code. Validating…
Documentation written by hand is a copy of the implementation, and copies drift — usually within a sprint, and always without anybody noticing. The annotations are verbose and…
The documentation was written in January and the API changed in March. Documentation written by hand is a copy, and copies drift — usually within a sprint.