Hello,
Years ago I worked with a team to create documentation that made use of Swagger2markup, as seen in
https://github.com/Swagger2Markup/spring-swagger2markup-demo, to integrate output from Swagger into a document that integrated a developer guide with API reference documentation. It was a large project (printed out to around 1500 pages). There were numerous reasons that making use of the SwaggerUI for API reference documentation was not feasible.
In the intervening years I have worked on numerous projects and now I am again working on documenting RESTful APIs. There are quite a lot of new hosting solutions and also some new tools that look interesting, however I am surprised to find that swagger2markup looks like is lacks the support that it needs right now.
While SwaggerUI has its merits, there are situations in which a standalone document is required. I don't know how participants might be attracted to open source projects. I've seen a tendency for developers to think in terms of working on new lightweight markup languages and then abandon the effort when they start to understand how complex the requirements are.
Perhaps brainstorming how to capture the above energy might result in useful strategies to attract attention to projects in the Asciidoctor toolchain that could use additional support, Swagger2markup being one. Since participation in some open source projects give developers substantial cred, and I've observed the impulse of some developer to create new lightweight markup languages only for them to fail when they realize the complexities, perhaps there is some way that opportunities to add to documentation tooling for lightweight markup languages might become a cool thing.
What do you think?
Locked
