I am looking at generating some API documentation, hopefully using Swagger, in a few different projects of mine. Having never used Swagger, I am trying to find a very simple solution to generating HTML documents via Maven.
The underlying REST framework being used in these projects is Jersey. I found documentation from Swagger but it doesn't seem to have any examples of simply producing HTML files. Most of their examples seem to embed the API documentation into the actual service itself.
So my questions are:
How can I generate HTML documentation with Swagger via Maven?
Is attaching the documentation along with the service normal to do with REST applications?
You will need to use swagger-codegen to generate an HTML.
https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
To generate the HTML doc with swagger-codegen, you will first need to generate an OpenAPI documentation. Since you are already using Jersey as your REST framework, it is probably the easiest to pull in swagger as a dependency into your project and annotate all your API servlets. Doing so, will tell swagger to read all your code and generate an OpenAPI spec. You can follow the steps in https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration to get started.
Good luck!
Related
Is there a way to generate a README.md file from swagger? I would like to put similar details that would be found in swagger web page plus some custom comments.
Also, is there a way to make a aggregator swagger web page? I want to have the all swagger web pages from all micro services also in a single place. This could enable me to take higher picture notion of my system and maybe do some queries like "how
many ways certain entity can get this another entity?".
Regarding README.md file - not sure what information you want to include in it, but you can write your own method which will do it using Swagger Parser in order to get required information from Swagger specification.
Regarding aggregated swagger - you can use Swagger-aggregate for this purpose.
I am building a rest api and part of the requirement is that we write documentation according to the open api specification. I am using (http://editor.swagger.io) to do this, and I find it irritating, and way less affective than creating normal javadoc. Is there a maven plugin, or something that can build documentation from comments in .yaml or .json format according to the open api specification? Thanks!
Seems like you're looking for that maven library https://springfox.github.io/springfox/docs/current/
It can automatically generate specifications in html
I have developed REST api using scala and spray. for documentation I am using Swagger API for listing all apis.
at home page. host:port/index.html , where all apis are listed, They are not coming in order,I am supposed to diplay version vise apis like version
1.0.0,
1.0.1,
2.0.0,
It seems they come randomly, I have also used position parameter in #API but seems not working, how would I provide proper ordering of apis.
Ordering of paths has been removed in Swagger v2.0, see discussions below.
https://github.com/swagger-api/swagger-core/issues/1050
https://github.com/swagger-api/swagger-core/issues/1151
Possible alternatives include:
go back to swagger 1.2
use of tags to better organize resources
locally change swagger-core as suggested in issue 1151
try to re-open the issue once more :)
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.
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.
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.
For RAML you have:
- https://github.com/kevinrenskers/raml2html
- https://github.com/mikestowe/php-raml2html
Give those a try ;)
Im trying to present swagger as an option to my team . And Ive written up a static json file which conforms with the swagger specification for a resource listing.
Is there any way in which I can generate a swagger like UI (http://petstore.swagger.wordnik.com/#!/pet) from this?
I tried Swagger4J but it doesnt seem to do much other than parsing the JSON.
Any thoughts would be appreciated.
Links : Generating Rest API documentation using swagger or any other tool (Doesnt help)
https://github.com/wordnik/swagger-spec/