Very basic question about Swagger and Flare
-
- Propeller Head
- Posts: 72
- Joined: Sun May 03, 2009 12:45 pm
Very basic question about Swagger and Flare
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
Thanks,
- Willie Williams
Re: Very basic question about Swagger and Flare
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.
Re: Very basic question about Swagger and Flare
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
Re: Very basic question about Swagger and Flare
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>]+)>'
"
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>]+)>'
"
Re: Very basic question about Swagger and Flare
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 ...
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>]+)>
Re: Very basic question about Swagger and Flare
I removed this script:
But that killed the language-switching functionality of the HTML2 output.
Code: Select all
/**
* marked - a markdown parser
* Copyright (c) 2011-2014, Christopher Jeffrey. (MIT Licensed)
* https://github.com/chjj/marked
*/
Re: Very basic question about Swagger and Flare
Okay, SO.
MadCap Import HTML Files Wizard CLAIMS the problem with importing the file is
Which you have to replace with
.
Then it craps out after that on:
but it only tells you
so you have to replace that, too:
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.
MadCap Import HTML Files Wizard CLAIMS the problem with importing the file is
in line 61. But the problem actually is the code right before it:"Invalid name character in '([^\s>]+)>'
Code: Select all
?<
Code: Select all
?<
Then it craps out after that on:
Code: Select all
?<([\s\S]*
Code: Select all
([\s\S]*
Code: Select all
?<([\s\S]*
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.
Re: Very basic question about Swagger and Flare
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:
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:
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>
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.
Re: Very basic question about Swagger and Flare
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.
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.
Re: Very basic question about Swagger and Flare
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.
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.
Re: Very basic question about Swagger and Flare
Code: Select all
<![CDATA[
/// Actual Script
]]>
</script>
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 ...
Re: Very basic question about Swagger and Flare
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.
https://www.youtube.com/watch?time_cont ... Na03oOakeQ
P.