I am looking for information about using Swagger output to create API documentation using Flare as an authoring tool. Has anyone done this? If so, what is your general workflow and how do you work with the Swagger files and import/output?
Thanks
Elizabeth
Anyone use Swagger and Flare to create API documentation?
-
- Propeller Head
- Posts: 18
- Joined: Sat Nov 09, 2013 12:51 am
Re: Anyone use Swagger and Flare to create API documentation
Could you explain further what you're trying to do? Swagger/OpenAPI generally IS an API documentation as far as devs are concerned. It lists all the operations, the requirements of each, and can contain comments/description for using each--everything you need to use the API, provided you know how to read a Swagger file. Are you trying to output a Swagger file from Flare? (not possible AFAIK, as Flare's publishing process is going the fill the file with junk) or embed the Swagger code within a regular Flare topic in order to provide more documentation?
I have been documenting some Swagger files recently, but my files are hardcoded examples. I add them the same as I would code samples: using styled <code> and <pre> tags in the text editor rather than the WYSIWIG. Flare's auto-indenting is a pain, here--for large chunks of code, I open the flare topic in Notepad++ and add or edit the code in there. If your Swagger files are relatively stable, I'd suggest creating them as snippets to drop where needed, as it makes it easier to find and edit the code (especially as the <code> and <pre> tags seem to screw up Flare's natural line-breaking, so you end up with your entire topic in one line).
I have been documenting some Swagger files recently, but my files are hardcoded examples. I add them the same as I would code samples: using styled <code> and <pre> tags in the text editor rather than the WYSIWIG. Flare's auto-indenting is a pain, here--for large chunks of code, I open the flare topic in Notepad++ and add or edit the code in there. If your Swagger files are relatively stable, I'd suggest creating them as snippets to drop where needed, as it makes it easier to find and edit the code (especially as the <code> and <pre> tags seem to screw up Flare's natural line-breaking, so you end up with your entire topic in one line).
Re: Anyone use Swagger and Flare to create API documentation
I haven't done it myself, but Ellis Pratt has two blog posts about this subject:
https://www.cherryleaf.com/blog/2017/06 ... eropenapi/
https://www.cherryleaf.com/blog/2017/06 ... cap-flare/
https://www.cherryleaf.com/blog/2017/06 ... eropenapi/
https://www.cherryleaf.com/blog/2017/06 ... cap-flare/
----------------------
Leslie T.
Leslie T.