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
Related
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.
In my SAM templates, my team has defined an API that is mostly to our liking. I would like to debug this API locally, but it isn't set explicitly as an Event under our Function. So sam local start-api fails with the error
Error: Template does not have any APIs connected to Lambda functions
How can I convince SAM that the API we have defined is the event meant to invoke this Lambda? What should I do to test this locally?
edit - to clarify, the current template structure looks something like
Lambda:
Type: AWS::Serverless::Function
Properties:
...
LambdaRole:
....
MAILAPI:
Type: AWS::Serverless::Api
Properties:
...
Not sure if this implements all the gateway params we defined so I wont mark this as resolved yet, but this is a promising start!
This allowed me to start the API as expected locally
Events:
Api:
Type: Api
Properties:
Path: /
Method: post
RestApiId:
Ref: MAILAPI
With (of course) our API resource defined under the MAILAPI label (edited question to show this)
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).
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