0

Problem:

I am searching for a library in Java or JavaScript (or maybe Scala) which is able to generate an HTML representation of Swagger, RAML or API Blueprint input.

Background:

The idea is to use it as a part of a (Play Framework) web app serving as an API catalog. API specifications would be added by users of the API catalog and resulting HTML representations would be generated/displayed.

It would give extra value if a API specification stub also is possible to create using a Java API. The API catalog web app has a data model which I would like to use when generating the API stubs.

Furthermore, it would give extra value if the same (or related another) library provided a nice HTML editor of the API specification language (Swagger, RAML, API Blueprint etc) supporting the user while editing.

nize
  • 1,012
  • 1
  • 11
  • 27

3 Answers3

2

Swagger offers a set of tools to do it.

Swagger-Core will enable you to produce Swagger documentation from your Play code. This is done at runtime and will change as your application changes.

Swagger-UI will read such docs and display them in an HTML format. It also allows you to execute the operations and has integration with security mechanisms if needed. The UI can be customized to have the look-and-feel of your application (like many have done so far).

Swagger-Editor allows for direct editing of Swagger documentation with interactive side-by-side view of the docs in an HTML format.

Swagger-Codegen can take such a documentation and generate both client and server code. You can customize the templates to suit your needs.

Ron
  • 14,160
  • 3
  • 52
  • 39
  • The goal is not to document the APIs of the Play app. Instead I am just using the Play app to manage all APIs in an enterprise. So, Swagger-core/codegen is not prio 1. However, I will investigate Swagger-UI and Swagger-Editor more closely. – nize Oct 28 '14 at 14:49
  • After looking in to Swagger more deeply I found that the online editor is good (doesn't even send spec content to the server - for those concerned with privacy) and that the html generator is built without the need for a backend. All is great. But then I found that it doesn't support XML Schema, which is a problem in the organization I am about to introduce the solution in. – nize Dec 19 '14 at 08:01
  • I assume you may have been the one asking about it on swagger-spec. There *are* possible solutions, but it would require some additional tweaking (depending on the complexity of the XML, it may require none). It'd be best to go over it on the google group. – Ron Dec 19 '14 at 08:06
0

There are several tools for for generating HTML from an API Blueprint, one of which is in Coffeescript and is called Aglio. You can see all of the tools here:

http://apiblueprint.org/

Also, Apiary is a service that uses API Blueprint and can be used for editing and hosting generated documentation, hooking up with Github to auto-generate from commits, providing some mocking APIs and some other cool stuff for teams and enterprises. You could check it out if you're wanting a solid service for your API documentation.

Stephen Mizell
  • 96
  • 2
  • I found Aglio https://www.npmjs.org/package/aglio but as I understand it you can't run it on a client browser, instead you need to have a nodejs backend or an executable on your system. I am looking for either a java or javascript HTML renderer. – nize Oct 28 '14 at 14:46
0

For RAML you have: - https://github.com/kevinrenskers/raml2html - https://github.com/mikestowe/php-raml2html

Give those a try ;)

nohorbee
  • 139
  • 1
  • 5
  • Yes, maybe I need to turn to these. The problem I see with them is that you need to run non-Java server side code, either php or nodejs. – nize Dec 19 '14 at 07:56
  • It's actually CLI, I don't see the need of a server side app there. About the not JAVA, I agree. It could be good to do the same in JAVA so it's easier to plugin with MVN. I will see if I can work on that too. – nohorbee Dec 22 '14 at 17:34
  • What I'm trying to do is to write a web application which lets the user upload a RAML file and from this the Web application should automatically generate an html documentation. The Web app is constructed by html, JavaScript and a Java backend. This is why I am looking for a Java or JavaScript library which transforms RAML to html. – nize Dec 23 '14 at 18:31
  • So, definitively, kevin's is the one to go! He is constantly working on it. I think this week he released a new version. – nohorbee Jan 22 '15 at 03:24