My group is thinking of adopting the OpenAPI spec as a standard for documenting REST APIs, but there's some disagreement about whether it's better to generate the specification document from code annotations (through Swagger codegen libraries), or to create the specification document manually (separate from the code).
I'm compiling a list of pros and cons and wanted to get a quick pulse check from the community. Can you tell me if I'm off-base about my pros and cons? *Cons of code annotation method* - the annotation syntax will differ by programming language - developers might not want to give others (tech writers, PMs, testers) access to their code, limiting collaboration - there's more of a learning curve to the syntax of code annotations than there is with the standalone YAML file approach - if engineers are unfamiliar with OpenAPI / Swagger and are uninterested in learning it, managing the spec within the code becomes like inviting yourself to someone's house without invitation - the specification file can only be generated *after* the API is coded - annotating the code puts the whole documentation process directly in the engineer's domain, prompting the engineer to be the primary person responsible for the documentation - not all codegen libraries support the latest version of the OpenAPI 3.0 spec - the annotations clutter up the code with a lot of documentation *Pros of code annotations method* - reduces potential for documentation drift - consolidates your doc and code in the same location - enables engineers to write documentation using their existing IDE - automatically creates the model definitions for requests and responses Am I correct in assuming that the prevailing trend is to create the specification file manually outside of the code repository, primarily so that the specification document can be used as a contract or blueprint for first testing and then building the API? Tom -- You received this message because you are subscribed to the Google Groups "Swagger" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
