I have the following openapi 3.0 compliant yaml file which I am trying to render via swagger. There are no errors reported in the yaml file, but the requestBody is not rendered on the swagger GUI. I just get a parameters field which is empty but nothing rendered for the request body, nor do I get any errors. Screenshot below.
paths:
/my-api:
post:
summary: My API Summary
description: My API Description
tags:
- Cost Center
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ReqBodyStruct'
What is the way to get the RequestBody also shown in the swagger gui ? Do I miss something ?
According to these two issues OAS 3.0: Support for media type examples (aka request/response body examples) #3437 and Examples are not showing #2651 from the Swagger UI github page this should be fixed in version 3.23.0 (of June 29, 2019).
Related
I am playing around with https://openapi-generator.tech/ and I have an example openapi.yaml file:
openapi: 3.1.0
info:
title: Sample API
description: My amazing description.
version: 0.0.9
servers:
- url: http://localhost:8080/v1
description: My amazing server description.
paths:
/users:
get:
summary: Returns a list of all users.
description: My amazing /users endpoint description.
responses:
"200":
description: (OK) A JSON array of user objects.
content:
application/json:
schema:
type: array
items:
type: string
I have tried the following generation command:
openapi-generator-cli generate -g go-gin-server --global-property=apiDocs=true -i ./openapi.yaml
both with, and without the --global-property=apiDocs=true part. Neither case generated an /api, /doc, or /docs endpoint.
What am I doing wrong?
Note that the server runs fine, i.e., I can curl the endpoints specified in the yaml file.
It doesn't look like the server stub generator go-gin-server supports adding this type of endpoint. If you look at the routers template that this generator uses you can see that no config option will generate an /api, /doc or /docs endpoint unless you have defined it in your spec.
It's not clear to me exactly what you are expecting from this endpoint, but you could define one of these endpoints in your spec and implement the behavior you would like, or you could customize the template to automatically add this endpoint during code generation
I'm working on huge yaml schema when I'm designing my swagger API service model and emphasized textI would like to save the model part in another file in order to have more flexibility and lisibility.
Following this documentation, I used this part of code :
components:
schemas:
Request:
title: Request
type: object
properties:
technicalData:
$ref: '../../schemas/foo.yaml/components/schemas/TechnicalData'
And in my foo.yaml file, I have stuff like this :
components:
schemas:
TechnicalData:
type: object
properties:
application:
type: string
applicationCode:
type: string
userId:
type: string
It works on localhost, but I face the following issue running my file on the enterprise deployement server :
Errors
Resolver error at
components.schemas.Request.properties.technicalData.$ref Could not
resolve reference because of: Not Acceptable
I am sucessfully able to browse my file through the browser locally.
Checking on the internet, I found some issue related to my topic, but unfortunately not very usefull :
https://github.com/swagger-api/swagger-editor/issues/1561
https://github.com/RepreZen/KaiZen-OpenAPI-Editor/issues/438
Add # between the file name and /components/...:
$ref: '../../schemas/foo.yaml#/components/schemas/TechnicalData'
^
I have an OpenAPI 3.0 definition with multiple servers:
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
When this definition is rendered in Swagger UI, the "Servers" dropdown shows the description of each server:
Is it possible to hide the server descriptions from this dropdown?
Swagger UI always displays the server description if it's provided, this is hard-coded:
https://github.com/swagger-api/swagger-ui/blob/master/src/core/plugins/oas3/components/servers.jsx#L125
As a workaround you can modify the API definition dynamically after it's loaded and remove server descriptions. To do that, edit your Swagger UI's swagger-initializer.js or index.html file and add the following onComplete function to the SwaggerUIBundle initialization code:
const ui = SwaggerUIBundle({
url: "https://path/to/your/openapi.json",
...
onComplete: function() {
let spec = ui.specSelectors.specJson().toJS();
let servers = spec.servers || [];
for (let i in servers) {
servers[i].description = ""
}
ui.specActions.updateJsonSpec(spec);
}
})
They haven't provided any option to replace this server's description in another place, but they have mentioned the description is optional in swagger specification of object representing a Server.
Swagger UI have not provided any rendering option for this.
The best use of description is define in a single word, like production, development, api, staging, etc..
If you really don't want in dropdown then you can remove it from your server list.
servers:
- url: https://development.gigantic-server.com/v1
- url: https://staging.gigantic-server.com/v1
- url: https://api.gigantic-server.com/v1
This part i am writing for your information, about how to use oas-servers,
I observed your server urls, these can be easily define in single url, how? using server variables.
servers:
- url: https://{environment}.gigantic-server.com/{version}
variables:
environment:
enum:
- 'development'
- 'staging'
- 'api'
version:
enum:
- 'v1'
Hope this help.
I'm evaluating Quarkus as backend, accessed by an angular frontend.
I wanted to use the openapi data provided by Quarkus via http://localhost:8080/openapi,
and generate via openapi-generator tools an typescript-angular client stub.
I used as first step the Quarkus Openapi Guide: https://quarkus.io/guides/openapi-swaggerui
But after running the unmodified example and retrieve the Openapi YAML-Data via the http://localhost:8080/openapi I noticed that the generated data is wrong and the openapi generator is not able to generate a client because of a stackoverflow error.
Problem: a self-reference in the Openapi-data for the SetFruit-Definition (last line):
openapi: 3.0.1
info:
title: Generated API
version: "1.0"
paths:
/fruits:
get:
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetFruit'
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fruit'
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetFruit'
delete:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fruit'
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetFruit'
components:
schemas:
Fruit:
type: object
properties:
description:
type: string
name:
type: string
SetFruit:
$ref: '#/components/schemas/SetFruit'
Is this a known problem, or is there some misunderstanding on my side.
Is there a way to work around this issue?
Many Thanks!
It should definitely not be generating a self-referencing definition! Could you perhaps open up an issue here:
https://github.com/smallrye/smallrye-open-api/issues
That library is the implementation behind the Quarkus support for this feature. If you could include a reproducer project that would be very helpful. Or at the very least give us some information about the Fruit and SetFruit java classes.
This issue will be solved in Quarkus 1.3.0.CR1, released next week.
We are working on Swagger Documentation for our Laravel REST API implementation.
Several of the POST endpoints will use CSV as the parameter content type.
Is there a way in Swagger to have the "Try It Now" function work with a CSV POST file upload?
Below is our documentation in progress
http://api.curvecompass.com/docs/#/
We have the Laravel POST function working correctly with the CSV endpoint, just not the Swagger docs.
swagger ui for open api 3.0 does not support file upload yet. you can watch the update here https://github.com/swagger-api/swagger-ui/issues/3641
You can try this.
consumes:
- multipart/form-data # and/or application/x-www-form-urlencoded
parameters:
- name: file
in: formData
description: The uploaded file data
required: true
type: file