In our old swagger 2.0 definitions, we have the following line:
"schemes" : [ "http", "https" ]
When deployed, we can see in swagger UI a select box that allows us to choose a scheme, which is quite useful when running locally.
Now, I'd like to convert our API to OpenApi. I tried doing so using the Swagger editor at https://swagger.io/ which has an automatic conversion tool, but the scheme line had disappeared. Is it deprecated in OpenApi? I couldn't find any guide on what to use instead. Any ideas what I should do to allow local developers to choose which scheme to use even using OpenApi definitions?
servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0
In this case, you'd want to define two servers (http and https).
servers:
- url: http://api.example.com/v1
- url: https://api.example.com/v1
Full documentation can be found here.
Related
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
I have a bunch of APIs that are documented as OpenAPI v3 specs.
Eg: foo.yaml, bar.yaml and baz.yaml
I also have a Web server that displays the specs in the swagger ui, so all my swagger models are easily consumable by devs, designers and so on.
My question: is there an easy way, using the javascript console, to give me a list of the resource paths?
I've had a quick look around the swagger ui source code but couldn't find anything useful, other than the SwaggerUIBundle object.
The API definition is accessible via ui.specSelectors.specJson(). The value is an Immutable.js Map.
You can use the following code to list all the paths:
let paths = ui.specSelectors.specJson().get("paths")
paths.mapKeys(key => console.log(key))
I have an JAX-RS application running on IBM Websphere Liberty Profile.
Also I have included SWAGGER 1.5.3.
The application compiles fine and generates swagger files in webapp directory. But when I try to access it via URL, it says NO API FOUND and the spinner keep spinning.
There are no errors registered on browser console neither any errors in server console.
I do not know whats wrong with it, without any errors its hard to debug.
Where can I see the detailed errors/exceptions.
WebSphere Liberty has native support for Swagger v2 using the apiDiscovery-1.0 feature. If you enable that you should see your APIs in https://host:https_port/ibm/api/docs.
By the way, there's support for the newer OpenAPI v3 spec, via the Microprofile OpenAPI programming model. You can use Liberty's mpOpenAPI-1.0 feature for that.
I have downloaded and browsed to the Swagger-UI dist/index.html file and it has loaded the sample Petstore APIs. However, I am not able to figure out how some features are functioning and hence not able to bring that to my own definition.
The sample Petstore shows a "VALID {...}" button at the bottom right hand side. However I don't see that when I navigate to my own API definitions. How do I enable it?
When I look up the petstore API specifications being rendered by Swagger-UI http://petstore.swagger.io/v2/swagger.jsonI am not able to figure out how are they plugging in the section below the Swagger Petstore description.
Contact the developer
This is a mailto link with an email address and subject line
Find out more about Swagger http://swagger.io doesn't show up either in the petstore json definition or the one that I am using.
Where is the sample picking this up from?
When I use the Swagger editor, it interprets the specification in a different way - most significantly showcasing the terms of use and license information appropriately. Does Swagger-UI not support those properties? Do I need to enable something in Swagger-UI to make them appear?
You need to be using the latest version of Swagger, Swagger Core 1.5 at least, to have these neat features in your own Swagger project.
The UI at version > 2.0 comes with the schema validation (the VALID button on the bottom of the page) built-in.
2+3. The Info object contains all the information needed for rendering Contact the developer, license and "More Info" links by the UI.
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.