Creating API Documents in Flare

[Toko]

Hi,

How does one create API documents in Flare?
Best practices and tips?
Should we somehow import from a another API tool such as Swagger etc?
Please help!!!

[Nita Beck]

I don't have a simple, one-size-fits-all answer. You might want to start by taking a look at this blog article by Cherryleaf: https://www.cherryleaf.com/2018/10/impo ... e-project/

[sds]

Hi there. I just completed an API development guide recently, specifically for outside developers to hook up with our API. I had a lot of fun with it. I formatted JSON code samples using the <pre> tag, after I formatted the code using an online JSON formatter. Turned out pretty neat. I checked out the link the other user gave you - it has some great samples. I put all of our methods on their own topics, though, and all of our Objects on their own topics, too. So, when a method returns an Object, the user can link over to get definitions of the fields within the Object. Other than that... what kinds of tips are you looking for?

[williamgwilliams]

Thanks Nita, for posting the link to that terrific Cherryleaf video on how Flare can be combined with the Swagger reference material. Our API develops use Swagger, and I was asked to create API documentation for a particular API. I did so, linking to the Swagger site from a (dummy) topic I called "Reference Documentation." I was interested to see that the excellent presenter in that video instead "imported" the Swagger site into a folder in the Flare TOC (via the Import HTML Files Wizard). He did say that you then have to edit the JavaScript that comes in with the Swagger, to achieve the look you want. I've done some JavaSrcript editing, but wasn't sure from the presentation how straightforward the editing would be.

The bummer I encountered with my API help was that, because the other API's presented in our company website just used Swagger itself as the documentation (with some non-reference content added in text fields Swagger provides), they decided to do the same with "my" API, to be consistent with the others. As a result, our developers get contacted about things like the intricasies of providing the authentication keys, and for code examples (which our developers respond to by sending them a PDF version of my Flare help system).