I want to generate a rest API with swagger codegen, but I have a big yaml with much more Models and APIs than needed.
So I want selective generate my Rest Service.
I have the following lines added to my pom.xml for restriction:
<models>MyModelA,MyModelB</models>
<apis>MyAApi,MyBApi</apis>
The models line work, only model A and B where generated. But the APIs don't seem to work, no APIs where generated. Am I using the wrong syntax? Should I pass the resource path into the APIs tag or the API name?
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 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!
I have some java objects Id like to create a swagger definition for. I dont expose controllers using the api model. Its just java models I need "described" so other projects in other languages can autogenerate the same model.
I have tried to setup a maven project and tried to genereate the swagger definition using
com.github.kongchen
But I just get an empty swagger definition file. My java object is not added as a definition under definitions in my swagger file.
How can this be achieved?
There is an other plugin that do this you can try it in order to solve your problem
https://github.com/conorroche/swagger-doclet
I hope my question is not too broad.
Our application has an Angular frontend and a Java backend and
we need both frontend and backened validation. At the moment, we manually code
validators in Typescript and Java that basically do the same thing.
Since that is not only tedious but also error-prone, we would like to define once (maybe in a JSON file)
which input fields have which constraints and ideally use a piece of software that auto-generates
Java and Typescript code based on that definition.
My question is: are there any open-source/commercial software solutions that take care of this?
It seems like a common enough problem, but I haven't come across
a proper solution yet. JSON schema seemed promising and since we're using swagger
anyway, I'd hoped that swagger-codegen would automatically take the supported JSON-schema keywords as constraints into account,
but I haven't figured out how it works. When I generate Angular code, constraints such as 'minimum' and 'maximum' are completely ignored,
and when I generate Java SpringBoot code, they only show up as annotations.
This is exactly what JSON Schema is designed for. Open API (swagger) modifies JSON Schema for it's own purposes, which doesn't include validation.
JSON Schema has validator implementations in most major languages allowing you to use the same schema to do the same validation on the front end and the back end. http://json-schema.org/implementations.html
Unfortunately, you likely won't be able to use the same schemas you use for your Open API service definition. I'm not aware of any validator implementations that support Open API's flavor of JSON Schema. I understand that Open API is trying to close the gap between their definition and JSON Schema, but a gap still exists.
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 ;)