This is an evolving area. What has been getting a lot of traction is to build the swagger description in a tool like swagger-editor, and generate the server code as part of the build process. That means the generated code will produce the annotations, etc., and “wire” to your functions which do the real work.
There are a bunch of benefits to this approach, including—as you brought up—the ability for tech writers to work on your spec. Of course they could break it (anyone could for that matter) and you would have tests run after the code is generated. For generation, consider using the swagger-maven-plugin in a profile to generate the server code from a spec. > On Jul 20, 2016, at 1:11 PM, arpit sharma <[email protected]> wrote: > > I am using swagger for api documentation. > > As a requirement ,technical writers want to edit stuff like api description > api operation description . These are people who do not understand code and > can write documentation in spreadsheets like excel . > > How do I manage api documentation now. All I can think of is to remove few > swagger annotations from api code and generate a basic swagger json > containing only technical content and read back api description from external > spreadsheet back and merge it to swagger json. > > Is this a good approach or do we have other ways to handle this scenario? > > -- > 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. -- 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.
