Ok. For existing projects, depending on the size of the API, often it’s easier integrating a library into your code and have that generate the documentation for you. In this case, the code will be the source of truth. Alternatively, you can use that as the starting point for your API documentation, and once you have it, maintain it separately.
For new APIs, we definitely recommend the design-first approach. Take a look at our editor – http://editor.swagger.io You can also generate client and server stubs from it, so even if you make changes to the description, the code changes are much easier. From: <[email protected]> on behalf of Nick <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Thursday, 27 April 2017 at 8:24 To: Swagger <[email protected]> Subject: Re: Best Practices for writing Swagger Docs I am writing in PHP, and I am trying to write docs for an existing API, but also figure out the best way to write docs for future projects On Wednesday, April 26, 2017 at 4:39:06 PM UTC-6, Ron wrote: Hi Nick, There are several approaches you can take, but they depend on whether you’re trying to document an existing API or write up a new one. Which is it for you? If an existing API, which language/framework do you use? From: <[email protected]> on behalf of Nick D <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Wednesday, 26 April 2017 at 14:58 To: Swagger <[email protected]> Subject: Best Practices for writing Swagger Docs Hello, I am wondering if there is a place that would let me know if there are any good practices with using Swagger to document my project? If there isn't, what are some opinions on how to best write and maintain Swagger documentation? -- 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. -- 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.
