swagger2markup
swagger2markup copied to clipboard
Swagger2Markup
Expanding example sections
The JSON request and response examples sections are great however they often take up a lot of room and by default it's useful to have them collapsed and only expanded as required. I wonder if others have experience of this and what they've done in their set up.
This looks promising https://sourceforge.net/projects/collapsefilter/ although it indicates it only works on XHTML. I'd like to support this on the HTML format generated. If it's possible it might be useful to build some of the mark up in our tool and provide a configurable option e.g. expandable example sections true / false. Although this might be difficult if it's very dependent on the final output format?
Cukedoctor has a feature like that and uses Asciidoctor as well. See http://rmpestano.github.io/cukedoctor/cukedoctor-documentation.html#Cukedoctor-Converter
Rafael Pestano is also in the same Slack channel, I can ask him how he has realized it.
Yes that's cool if we can support it, but the problem is that we have to manage different markup outputs with their own capabilities and it can be frustrating (Markdown for example is very limited). For now, we targeted the least common denominator. It means we have to change the philosophy and try to generate the best for each output markup ?
Hi @RobWin, sure!
What do you need? If you are ok with Cukedoctor's solution I can try to port it to swagger2markup but I'm not sure how it would be done in markdown.
If you want to hack by yourself, below is some explanation of what is implemented in cukedoctor.
For min/max Cukedoctor is using asciidoctor macro processor which is part of the Asciidoctor extension api. A macro processor replaces parts of your adoc file (the macros) with desired markup, example:
test.adoc:
gist::123456[]
The (pre registered) gist macro processor will transform this macro (gist::) in desired markup, see example here.
And here is Cukedoctor minmax macro processor: https://github.com/rmpestano/cukedoctor/blob/master/cukedoctor-extension/src/main/java/com/github/cukedoctor/extension/CukedoctorMinMaxExtension.java
Note that showFeatureScenarios/hide function is added by ScriptsExtension, a post document processor responsible for scripts.
In a post document processor you don't need to place macros into your adoc file but you have to manipulate the hole html dom. Here is Cukedoctor filter extension, a post document processor which adds a search box in resulting documentation.
Note that in both cases you'll have to deal with html dom but macro gives you an entry point (the macro) where in post processor you have to query the entire document in order to change it.
Summarizing I would use macro if I had to manipulate multiple parts of the document and post process to add things to specific places of resulting document (e.g footer, a search box etc..).
I hope it helps.
