Having a master JSON file
{"swaggerVersion":"1.2",
"apiVersion":"1.0",
"apis":[{"path":"/api1"},{"path":"/api2"},{"path":"/api3"},{"path":"/api4"}]}
and JSON files for each of the 4 APIs, which working well with the Swagger library each.
But when I tried to place it all into one JSON file like
{"swaggerVersion":"1.2",
"apiVersion":"1.0",
"apis":[{<api1 json file contents>},{<api2 json file contents>},{<api3 json file contents>},{<api4 json file contents>}]}
it didn't work.
What is proper way to do merge several Swagger v. 1.2 files into a single file?
According to the Swagger 1.2 Specification you just cannot do that.
The "master" JSON file (as you called it) is the Resource Listing of a Swagger API, which just contains an "inventory of the available resources".
The "apis" property of this JSON document is expected be an array of Resource Objects with a specific structure:
{
"path": "/pets",
"description": "Operations about pets."
}
Quoting the API Declaration section of the spec:
The API Declaration provides information about an API exposed on a resource. There should be one file per Resource described. The file MUST be served in the URL described by the path field.
Take a look at the demo application to view all service documentations at a single location: https://github.com/varghgeorge/microservices-single-swagger
Repo shows how to create a springboot application which will serve as a single place for all your springfox/swagger documentations.
Swagger documentation from different services/locations can be configured in this server using yaml config. Details are on the github location.
Related
I have to change the path of the swagger json file, in nestjs documentation it is http://localhost:3000/api-json but for the standard have to keep it
http://localhost:3000/api/openapi.json
Let me know if there is any possible solution for it.
since v6.2 of #nestjs/swagger you can change that value using the jsonDocumentUrl/yamlDocumentUrl option like so:
SwaggerModule.setup('api', app, document, {
jsonDocumentUrl: 'openapi.json'
});
Is there any way to visualize swagger YAML file inside ReadeMe.md. Only way I can put file
[Swagger Codegen](/assets/swagger.yaml)
my structure for codebase is
Project
src
assets
swagger.yaml
ReadeMe.md
You can try convert the swagger.yaml to markdown, then put it in readme.
Conversion tools like: https://github.com/syroegkin/swagger-markdown
There's a online demo here: https://swagger-markdown-ui.netlify.app/
Some days ago I started a REST API in JavaEE 7, I implemented a single class with three methods and implemented succesfully Swagger and Swagger-UI in the project, which showed the three endpoints I implemented succesfully in the generated JSON.
However, I migrated to JavaEE 8, and after this change Swagger detects several unknown endpoints, like the "default" ones (this capture shows only part of all of them):
Investigating a bit I discovered that these endpoints may belong to a JPA REST API in Eclipselink implementation, as described here https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-open-api-swagger-support and here https://www.eclipse.org/eclipselink/documentation/2.4/solutions/restful_jpa004.htm#CHDFCFFA
Despite they appear in the generated JSON, all of them contain variable paths, so I can't access them following the path given by Swagger, even inventing some parameters like "version" using the webs above examples.
The Swagger version I use is v3, aka OpenAPI version. I specify OpenAPI properties with #OpenAPIDefinition in the endpoint class, which also contains a #Tag annotation to group them and the three methods contain #Operation tag with their own #ApiResponse. There is no more Swagger/OpenAPI annotations/files/classes written by me.
The question is, how can I make Swagger ignoring these endpoints?
Thanks
Finally I have found a solution. The case is that Swagger scanner engine scans the whole project, ignoring if the class and his methods have #Operation or not. If my hypothesis is true, some Eclipselink classes could have Swagger annotations (I'm not sure), so when Swagger scans, if finds them and add them to the JSON/YAML.
The solution is creating/adding to the existant openapi.yaml (it can have several names and can be in several locations, as enumerated here: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-configuration#known-locations) this:
resourceClasses:
- com.path.to.your.package.Resource
prettyPrint: true
cacheTTL: 0
scannerClass: io.swagger.v3.jaxrs2.integration.JaxrsAnnotationScanner
readAllResources: false
Instead of resourceClasses it can be written resourcePackages, and then it should be specified the whole package and the class in the same style as used to specify the package. To be honest, this property does not affect to my problem.
The solution comes on setting readAllResources to false. The reason is here, in a note: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation
Blockquote
Note: swagger-jaxrs2 reader engine includes by default also methods of scanned resources which are not annotated with #Operation, as long as a jax-rs #Path is defined at class and/or method level, together with the http method annotation (#GET, #POST, etc).
I hope this solution serves for anyone if he/she has to face the same problem.
My organization has a lot of APIs for different projects. I need an OpenAPI implementation that allows me to create a standalone portal that contains all these APIs (more like a repository) for all our products.
Is there an OpenAPI that supports this?
Another option would be: to be able to merge several instances to a single OpenAPI instance.
There are several ways to implement API catalogs.
Swagger UI (open-source)
Swagger UI 3.0.19+ can display multiple API definitions using the url parameter.
// index.html
const ui = SwaggerUIBundle({
dom_id: '#swagger-ui',
urls: [
{name: "petstore", url: "http://petstore.swagger.io/v2/swagger.json"},
{name: "instagram", url: "https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml"}
],
"urls.primaryName": "petstore", // default spec
...
Result:
Since Swagger UI is open source, you can customize its layout and look&feel as your needs dictate.
SwaggerHub (commercial)
SwaggerHub provides API catalog hosting for teams & organizations, either in the cloud or on premises. SwaggerHub also supports API design, collaboration, code generation and workflow integrations among other things.
Disclosure: I work for the company that makes SwaggerHub.
To do that, a great solution is to use SwaggerHub as indicated. However, this tool is not free for private API.
I had the same need, so, to help community in OpenAPI design, I wrote a new tool named "OpenAPI Dev Tool" (in github).
With OpenAPI Dev Tool, we can deploy several documentations (for several use contexts) for Swagger UI / Redoc with hot reload feature, like an SwaggerHub.
It is really easy to use.
Each API is indicated in a configuration file :
{
"folder": "./specs", // Root folder where the specifications are stored
"specs": [ // Array of specifications (several specifications can be exposed)
{ // First specification file
"file": "/petstore.yaml", // Relative path of the specification main file (from "folder" parameter). It has to be an OpenAPI file in YAML or JSON.
"context": { // Object used for template generation (see Template usage chapter below)
...
}
},
{ // Second specification file
"file": "/petstore2.yaml"
...
}
]
}
Then, you can serve the whole API just by hitting npx openapi-dev-tool serve
Open your browser with http://localhost:3000 et voilà :)
I am using TEST Application class which consumes three different resource classes
example:-HondaApplication.java
-carResource.java
- bikeResource.java
- planResouce.java
I am getting one JSON file by using OpenAPI-Specification swagger generator.
so I am looking for three different JSON file.
Any help would be appreciated.