Swagger & Swagger UI use "Schemas" and "Models" interchangeably. I'd like to refer to them as Models on my Swagger UI instance (rather than Schemas), but can't find where to make this change.
I've attached 2 images that show where I'm referring to. I'd like to erase all references of "Schemas" from the page, and replace them with "Model", similar to how it appears on many of Swagger's test sites (example: petstore.swagger.io) that they've created.
Image 1
Image 2
Swagger & Swagger UI use "Schemas" and "Models" interchangeably.
Just to clarify - Swagger UI uses "Schema" when rendering OpenAPI 3 definitions, and "Model" when rendering OpenAPI 2.0 definitions. With this in mind, "Model" is sort of an outdated term.
If you still want to see the "Model" label in Swagger UI regardless of your OpenAPI version, you'll have to fork Swagger UI, change the label in the code, and build and use your own version. (And rebuild it whenever you want to use a newer Swagger UI release.)
The lines you need to change are:
src/core/components/model-example.jsx
{isOAS3 ? "Schema" : "Model" }
change to
"Model"
src/core/components/models.jsx
<span>{isOAS3 ? "Schemas" : "Models"}</span>
change to
<span>"Models"</span>
Related
I have developed a rest-api client (in java) customised to the needs of my product. I wanted to generate tests using my rest api client using swagger-codegen modules based on yaml-file.
I have already extended DefaultCodegenConfig & even tried implementing the CodegenConfig interface to build my custom jar. I have customized the api.mustache and api_test.mustache files and passing them in the constructor and processOpts() method of my CustomCodeGen that extends DefaultCodegenConfig.
However, I want to use the custom/new mustache template variables that I have added in my customised api.mustache.
For e.g. if refer to standard api.mustache, the template variables it typically uses are
- {{classname}}
- {{#operation}}
- {{#contents}}
- {{#parameters}}
etc.
Now, I want to introduce a new template variable, let's say {{custom_param}}. Now I am not clear how do I integrate this new template variable with the implementation.
Looks like from this Mustache-Template-Variables published here, swagger-codegen does not allow adding new template-variables and perhaps we are restricted to only the variables mentioned on this page.
So, is there some way to make the new template variables work ?
Some time ago I added the uniqueItems parameter for bean validation as it was not getting processed by the engine even though it was a part of the implemented JSR.
So I believe codebase needs to be updated to use your own variable which is only possible if you fork the code.
In case it helps, these two were the PRs:
For query parameters: https://github.com/swagger-api/swagger-codegen/pull/10154.
For body parameters: https://github.com/swagger-api/swagger-codegen/pull/10490.
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've read other questions about how to order using apisSorter and operationsSorter.
However in my case I want to be able to define a custom order to list several POST methods in a logical workflow order.
The catch is, since I'm using swagger-codegen, I'm only writing the swagger spec in a yaml file and can't see how to define a custom order then?
I am trying to generate python client from a swagger yaml file. It works fine, except that the response models are all snake cased(words sep. by underscores) instead of camel cased. I provided the camel cased versions like this:
definitions:
serviceResponse:
type: object
properties:
serviceResponseInternal:
type: object
The generated code has a ServiceResponse object which has an internal field service_response_internal. I would like it to respect the convention and just have serviceResponseInternal instead of underscored seperated names. How do I achieve this?
Assuming you're using Swagger Codegen, you can customize the toVarName in the Python code generator:
https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PythonClientCodegen.java#L180
Can you elaborate on why you don't want to go with snake case for model properties (which should conform to Python style guide)?
UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.