What is the difference between Swagger UI vs Swagger CodeGen?
I read the description in https://swagger.io/tools/. It sounds like Swagger Editor, UI, and codeGen are totally different tools. If I want to generate .Net server stubs and visualize them, does it mean I need to use both UI and CodeGen?
Yes, they are different tools for different purposes.
Swagger UI is a documentation renderer, basically an HTML page. You point it to an OpenAPI definition (YAML or JSON file), and Swagger UI produces API documentation that looks like this. You can host it on your website.
Swagger Editor is an editor where you can write OpenAPI definitions manually, or load/paste arbitrary OpenAPI definitions to check them for syntax errors. Swagger Editor also has Swagger Codegen integrated into it, accessible via the "Generate Server" and "Generate Client" menus.
Swagger Codegen is a code generator. You can use it to generate server stubs and client SDKs from an OpenAPI definition. For example, here's how to generate an ASP.NET server stub using Swagger Codegen CLI (line breaks added for readability):
java -jar swagger-codegen-cli-3.0.21.jar generate
-i https://petstore.swagger.io/v2/swagger.yaml
-l aspnetcore
-o .\aspnetcore-server
Related
I am building up a CDI/REST Environment as basis for several projects by using hammock. What I would like to have besides CDI and REST is also json schema for generating payload classes and an automatically generated REST API documentation via swagger ui.
I am now at the point where everything works (Weld3, Resteasy, Undertow, Swagger Core, Json Schema). The only thing missing is the integration of swagger UI into my hammock stack.
In another project I already worked with swagger UI. As far as I know it is based on HTML + JS with an entry point index.hml. How do I integrate this into my hammock stack. How to tell the undertow that there is a index.html and where to find it ?
I think my question is not only related to swagger, but to the idea to have the hammock stack with additional static html content.
John Ament has added a swagger module for Swagger 2.0-rc3 to Hammock 2.1-SNAPHOT (will be released as part of Hammock 2.1):
https://github.com/hammock-project/hammock/tree/master/swagger
As for hosting Swagger UI inside a Hammock app, you can add a few files from swagger-ui/dist/* to Hammock's static resources path:
https://github.com/hammock-project/hammock/wiki/Native-Filters#static-resources
We use Apache Ant for our project build and were thinking of extending the same for getting swagger 2.0 specs .json generated for our REST API docs. I found an ant task : https://github.com/cstroe/swagger-ant-task
which would invoke the same swagger core maven plugin, but some dependency jars have been changed in the github package due to which I am getting 'No Such Method' Exception for getApiInfo() method in ApiSourceInfo.java.
We cannot use maven just for generating API docs. I needed some help in finding a way by which I can use swagger core tool of generating docs using swagger annotations in the API definition file. Using ant wrapper for the maven plugin was one way but I am not not able to leverage it. Is there any other workaround?
Or to frame it otherwise, whats the right swagger tool/plugin to generate Swagger 2.0 jsons out of JaxRS annoations which works with ANT.
Any suggestion would be much appreciated.
Thanks
I've developed a REST API anotated with Swagger annotations.
I've been able to show the api documentation on a swagger-ui application, very nice.
The problem:
I'm trying to generate clients acording this specification using the url provided by swagger acording my anotations.
The porblem is it seems to be imcompatible, or at least, I don't see how to do the swagger editor reads my url and from then on, generate clients. But swagger editor reports me about some errors...
It's possible to integrate my anotated swagger api with a swagger editor?
Thanks.
The question seems a bit confusing.
If you are trying to generate clients from your REST API Swagger spec, then you should take a look to Swagger-Codegen project.
Description of project:
swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
Link to repository: https://github.com/swagger-api/swagger-codegen/
Link to official page: http://swagger.io/swagger-codegen/
Not sure if I understand the question correctly. If you want to generate API clients online, you an use http://generator.swagger.io (besides http://editor.swagger.io). Here is an example to generate API client for Java:
curl -X POST -H "content-type:application/json" -d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' http://generator.swagger.io/api/gen/clients/java
Swagger editor is used only for editing a swagger spec in either json or yml format. It does not deal with swagger annotations in any way. However, some of the server skeletons that are generated on the swagger-editor website contain annotations. The annotations are a way of reverse engineering your API to generate a json file so that swagger UI can render a webpage based on the public url path to your swagger.json file.
If you are maintaining a swagger spec json file anyways, the annotations aren't really needed, you might as well just serve up the raw swagger.json itself, rather than the json that is generated by the annotations.
As to your question, "Is it possible to integrate your API with swagger editor?"... Anything is possible, but I'm not sure as to how or why you want to integrate them.
I am using Swagger with Jersey 1. It generates spec in Swagger spec v1.2. Most of the tools out there (e.g. Editor ) require spec v2.0. Is there a way to generate spec v2.0 ?
I actually wanted printable/static docs like bootprint-swagger which also required spec v2.0.
I have not tried it myself, but https://github.com/lucybot/api-spec-converter seems to be able to convert Swagger 1.2 to Swagger 2.0
I'm not sure if it is an "official" Swagger-Tool, but it is just two clicks away from the Swagger-1.2-to-2.0-Migration-Guide, so I guess its like "half-official" at least.
I might try to incoorporate it into bootprint-swagger so that it supports Swagger 1.2 as well. I've just created an issue at github so that it is not forgotten.
I have a Dropwizard application with Swagger annotated Java resource classes. I'm also creating programatic REST resources which, of course, don't end up in the generated Swagger JSON. Is it possible to programmatically add operations via the Java Swagger API such that they end up in the generated JSON along with the annotated resources?
I tried using DefaultJaxrsApiReader.appendOperation but it had no effect.
I'm using com.wordnik:swagger-jaxrs_2.10:1.3.12
EDIT
I ended up just writing a Servlet filter to update the Swagger JSON response. It would be great to get #fehguy's suggestions working somehow. I think that swagger-jaxrs_2.10:1.3.12 isn't new enough to support those POJOs.
as of swagger-core-1.5.1-M1, you can build a swagger POJO which simply needs to be returned by your web application. That means, you can programmatically create the Swagger object and serve it up as JSON from your web service.
For examples of how to build a swagger pojo you can look at the source or an example (test) of building one.
You can also mutate the generated swagger object in your application. That means you can dynamically generate / modify swagger at runtime. There is an example in the swagger-codegen project, where the online code generator (swagger-generator) will detect what languages are enabled in the code generation logic via SPI, and update the swagger spec accordingly with the options:
https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-generator/src/main/java/com/wordnik/swagger/generator/DynamicSwaggerConfig.java