Openapi YAML wrong, cannot generate client-stubs - quarkus

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.

Related

How to generate API docs with openapi-generator.tech

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

Swagger schema reference in another file

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'
^

AWS enable caching with queryStringParameter PathParameter for SAM API Gateway

I would like to enable caching for API Gateway for my serverless functions, but having hard time to understand where to do it and what way.
I have tried to set up queryStringParameters in my serverless functions but that results in error, also tried to add them under my GLOBAL Api but no luck (also would prefer avoid doing this in global)
Also checked my resources in the API Gateway and caching is disabled for RequestParams and QueryStringParams are missing from there.
As a reference:
https://awslabs.github.io/serverless-application-model/internals/generated_resources.html
As a reference:
https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessapi
As a reference:
https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Template
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Globals:
Api:
EndpointConfiguration: REGIONAL
CacheClusterEnabled: true
CacheClusterSize: "0.5"
MethodSettings:
- CachingEnabled: true
CacheDataEncrypted: true
CacheTtlInSeconds: 60
HttpMethod: "*"
ResourcePath: "/*"
Resources:
......
GetItem:
Type: 'AWS::Serverless::Function'
Properties:
Handler: GetItem.handler
Runtime: nodejs8.10
Timeout: 20
CodeUri: "codes"
Events:
GetItem:
Type: Api
Properties:
Path: /item/{itemCode}
Method: get
......
***********************************EDIT*********************************
Found out if API Gateway does not know about the params then it will ignore it for caching https://forums.aws.amazon.com/thread.jspa?messageID=915838&#915838
I have tried to add multiple methodSetting entries to the template, and it seems the CF dont ignore it, but still the same result. Also im not sure how to do the same for queryStringParameters if possible.
- ResourcePath: "/~1item~1/~1{itemCode}"
CachingEnabled: true
CacheDataEncrypted: true
CacheTtlInSeconds: 60
HttpMethod: "*"
***********************************EDIT*********************************
I would prefer a way to enable the caching for the RequestParams and QueryParams under every resource aka 'AWS::Serverless::Function'
Your help is much appreciated.
At this point there is no support from SAM framework to do this. They are planning to release an update where they enable the function more on this link: https://github.com/awslabs/serverless-application-model/issues/1140
Until then the only solution i was able to come up os to create a CloudFront distribution in front of the API gateway, its kind of waste of resource but it works nicely.

Complete list of possible policies in a sam template

I'm trying to find a complete list of policies that can be added to the sam's template but I can't find any information either on amazon's official documentation nor by googling for it.
I'm in the process of converting a lambda application to sam and it requires a lot of polices so I need a list of what policies exist and what they are named. So what are the possible policies you can put on a sam application?
My template:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
AWS Serverless Application
Sample SAM Template for AWS Serverless Application
Globals:
Function:
Timeout: 20
Runtime: java8
Resources:
example:
Type: AWS::Serverless::Function
Properties:
CodeUri: target/aws-lambda.zip
Handler: com.example.ExampleRequestHandler::handleRequest
Events:
example:
Type: Api
Properties:
Path: /example
Method: post
Policies: # <- This field
- AmazonDynamoDBFullAccess
all_aws_managed_policies.json
A list of all AWS managed policies and they're [sic] policy documents as well as a short script to generate the list.
I [wrote] this code so that I could easily see the details of the managed policies since AWS doesn't publish them.

swagger is not rendering requestbody

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).

Resources