Anyone use Swagger and Flare to create API documentation?

This forum is for all Flare issues not related to any of the other categories.
Post Reply
efilippo
Jr. Propeller Head
Posts: 2
Joined: Tue Dec 06, 2016 1:41 pm

Anyone use Swagger and Flare to create API documentation?

Post by efilippo »

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
Sofie Bird
Propeller Head
Posts: 18
Joined: Sat Nov 09, 2013 12:51 am

Re: Anyone use Swagger and Flare to create API documentation

Post by Sofie Bird »

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).
LeslieT
Propeller Head
Posts: 40
Joined: Fri Feb 29, 2008 11:32 am

Re: Anyone use Swagger and Flare to create API documentation

Post by LeslieT »

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/
----------------------
Leslie T.

Image
Post Reply