Very basic question about Swagger and Flare

This forum is for all Flare issues not related to any of the other categories.
Post Reply
williamgwilliams
Propeller Head
Posts: 72
Joined: Sun May 03, 2009 12:45 pm

Very basic question about Swagger and Flare

Post by williamgwilliams »

I use Flare for all the help systems I create. The latest version of one of our API's is being presented via Swagger. They want me to use the Swagger presentation for the basic documentation of the methods and parameters (especially since it allows you to "Try it out" right in the URL). But there have to be infrastructure topics on things like how to generate an authorization token, how to use the SDK, and so on. I've seen an API help system that seems to "embed" the Swagger presentation of the Get, Post, Put, and other requests into a larger Flare help system. But it's not obvious to me how this was done. Has any of you done this? If so (or even if not), have you any basic tips on doing it? The "Swagger" part of that help system I've seen is called the "API Reference," while the other sections are things like "Getting Started," "Key Concepts," and "Connector Workflow." I guess my main question is, if I set up a project with topics like those, how do a make our existing Swagger site become the "API Reference" topic (or whatever I call it)?

Thanks,

- Willie Williams
dalogan
Propeller Head
Posts: 11
Joined: Fri Sep 11, 2009 8:12 am

Re: Very basic question about Swagger and Flare

Post by dalogan »

Hello, I was wondering if you have received anymore information about using Swagger. I know this question was posted a long time ago. We have some writers on our team that are taking the Swagger content and importing into Flare to create the output.
benpja
Propeller Head
Posts: 13
Joined: Thu Sep 07, 2017 7:00 am

Re: Very basic question about Swagger and Flare

Post by benpja »

Hi have either of you got any further information. I am exploring the use of swagger to export files and importing/use them within flare to generate documentation. Any help or guidance would be gratefully received
Kathy_123
Propeller Head
Posts: 39
Joined: Thu Oct 04, 2012 9:40 am

Re: Very basic question about Swagger and Flare

Post by Kathy_123 »

I am getting started using this video to play around, but am having a few problems (Flare 2019)

https://www.cherryleaf.com/2018/10/impo ... e-project/

I got it to work with HTML output from swaggerhub, but Importing "html2" output from Swaggerhub gives me an error and I cannot complete the import: " "Invalid name character in '([^\s>]+)>'
"
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

Kathy, I'm getting the same error, whether I import it from my desktop (after exporting from SwaggerHub) or from my GitHub local repository (one suggestion I found online was that GitHub was inserting characters).

Honestly, I'm ready to go Slate or something at this point, rather than introduce Flare into this environment.

It's part of the HTML2 output ...

Code: Select all

(function(){var block={newline:/^\n+/,code:/^( {4}[^\n]+\n*)+/,fences:noop,hr:/^( *[-*_]){3,} *(?:\n+|$)/,heading:/^ *(#{1,6}) *([^\n]+?) *#* *(?:\n+|$)/,nptable:noop,lheading:/^([^\n]+)\n *(=|-){2,} *(?:\n+|$)/,blockquote:/^( *>[^\n]+(\n(?!def)[^\n]+)*\n*)+/,list:/^( *)(bull) [\s\S]+?(?:hr|def|\n{2,}(?! )(?!\1bull )\n*|\s*$)/,html:/^ *(?:comment *(?:\n|\s*$)|closed *(?:\n{2,}|\s*$)|closing *(?:\n{2,}|\s*$))/,def:/^ *\[([^\]]+)\]: *<?([^\s>]+)>
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

I removed this script:

Code: Select all

  /**
   * marked - a markdown parser
   * Copyright (c) 2011-2014, Christopher Jeffrey. (MIT Licensed)
   * https://github.com/chjj/marked
   */
But that killed the language-switching functionality of the HTML2 output.
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

Okay, SO.

MadCap Import HTML Files Wizard CLAIMS the problem with importing the file is
"Invalid name character in '([^\s>]+)>'
in line 61. But the problem actually is the code right before it:

Code: Select all

?<
Which you have to replace with

Code: Select all

?<
.

Then it craps out after that on:

Code: Select all

?<([\s\S]*
but it only tells you

Code: Select all

([\s\S]*
so you have to replace that, too:

Code: Select all

?<([\s\S]*
Then the HTML2 output will import.

However, it won't work like it does as output from Swagger with the code switching. You get a lot of code on the imported HTML page which doesn't do any good.

So, this integration is in the dustbin. If I can't get Flare to do this, I'll find something else that will do it, I guess. Probably WordPress or something that can iFrame in the Swagger HTML2 content.
You do not have the required permissions to view the files attached to this post.
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

So I switched attack methods, and linked the full HTML2 output to be referenced in an iFrame instead. I had to get some help from MadCap support to fix some bungling I did in the coding, but this rudimentary link got me going in the right direction:

Code: Select all

<p><iframe src="file:///C:/Users/LB/Dox/Central/MadCap-Flare-Tests/HTML2-Test/index.html" width="1500" height="2000" frameborder="0"></iframe>
        </p>
So it passes for my proof of concept. The width and height need adjusting, but it's got me started in the right direction without needing to do anything to the swagger output except host it on my preferred site (likely the same place the HTML5 from Flare will be).

Caveats:
  • This is just a proof of concept with a couple of endpoints.
  • The Swagger.yaml I'm using is basically ALL of the endpoints in one file, and it's hand made (not generated from code).
  • I plan to get developers on board with putting the documentation that generates the swagger in a way that will let me work with conditional text and put the endpoints in the order needed for document flow and to leverage conditional text.
  • I haven't even gotten into what I'll need to do to swagger output to change the color scheme to match our scheme for a seamless look.
You do not have the required permissions to view the files attached to this post.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Very basic question about Swagger and Flare

Post by Psider »

Left field theory - I don't use swagger and have only the most rudimentary understanding of javascript. But. The import seems to be croaking on javascript.

Could you try wrapping the script in CDATA code and see if that imports? If understand right, it *might* stop the import process trying to generate HTML code out of the triangle brackets.
https://en.wikipedia.org/wiki/CDATA

Something like:
<script>
<![CDATA[

actual script code goes here

]]>
</script>

Not ideal if you have hundreds of files, obviously. But it would be interesting to see if it would import with that change.

Oh, and I think your iframe import is great! Good luck getting everything working. I look forward to hearing more.
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

Yeah, I've only used basic HTML and and am just getting into Flare doing this kind of work; I've mostly worked in places where the kinks were already worked out.

I'll keep that in mind; and yeah, part of it will depend on how we decide to divvy up our API work to condition out public vs partner vs private endpoints.
LorenaB
Propeller Head
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: Very basic question about Swagger and Flare

Post by LorenaB »

Code: Select all

<![CDATA[ 

/// Actual Script

]]>
</script>
Nope, didn't help, but thank you for the suggestion.

Also, linking information from existing HTML2 output in iFrames makes the content invulnerable to a basic search (not going to add a third party search integration if we don't need to), and my SME has clarified some of their requirements that may take Flare out of the running ...
oceanclub
Sr. Propeller Head
Posts: 277
Joined: Thu Oct 10, 2013 4:45 am
Location: Dublin

Re: Very basic question about Swagger and Flare

Post by oceanclub »

I'm having the same problem. What I don't understand is that in this tutorial, the user imports the html2 format fine. Not sure what they did differently:

https://www.youtube.com/watch?time_cont ... Na03oOakeQ

P.
Post Reply