I'm using OpenAPI to Document a Microprofile application. As the Endpoint contains a large set of methods, I'd like to know if it's possible to filter through the /openapi REST, so that it returns just a specific Path, for example "/users".
Thanks
You can have multiple paths selected. In openapi file the whole path section is called "paths" (so even the name is plural). If you're not sure how to use it, walk through openapi's in the "search" section of Swagger portal (you need to be logged in for this).
Example:
paths:
/{users}:
options:
security:
summary: "Temp summary"
description: "Temp description"
tags:
- "TAG"
parameters:
..
/test/{table}:
options:
security:
summary: "Temp summary"
description: "Temp description"
tags:
- "TAG"
parameters:
..
/test2/user/{id}:
options:
security:
summary: "Temp summary"
description: "Temp description"
tags:
- "TAG"
parameters:
as per our use case we found this to be working.
Annotate your endpoint with #Operation and add a hidden = true parameter to the annotation.
Here in Kotlin:
#GET #Path("/{id}")
#Operation(
summary = "your summary",
hidden = true
)
fun getDataset(#RestPath id: String): Response {
....
}
Related
I have a Type: AWS::Serverless::HttpApi which I am trying to connect to a Type: AWS::Serverless::StateMachine as a trigger. Meaning the HTTP API would trigger the Step Function state machine.
I can get it working, by only specifying a single input. For example, the DefinitionBody when it works, looks like this:
DefinitionBody:
info:
version: '1.0'
title:
Ref: AWS::StackName
paths:
"/github/secret":
post:
responses:
default:
description: "Default response for POST /"
x-amazon-apigateway-integration:
integrationSubtype: "StepFunctions-StartExecution"
credentials:
Fn::GetAtt: [StepFunctionsApiRole, Arn]
requestParameters:
Input: $request.body
StateMachineArn: !Ref SecretScannerStateMachine
payloadFormatVersion: "1.0"
type: "aws_proxy"
connectionType: "INTERNET"
timeoutInMillis: 30000
openapi: 3.0.1
x-amazon-apigateway-importexport-version: "1.0"
Take note of the following line: Input: $request.body. I am only specifying the $request.body.
However, I need to be able to send the $request.body and $request.header.X-Hub-Signature-256. I need to send BOTH these values to my state machine as an input.
I have tried so many different ways. For example:
Input: " { body: $request.body, header: $request.header.X-Hub-Signature-256 }"
and
$request.body
$request.header.X-Hub-Signature-256
and
Input: $request
I get different errors each time, but this is the main one:
Warnings found during import: Unable to create integration for resource at path 'POST /github/secret': Invalid selection expression specified: Validation Result: warnings : [], errors : [Invalid source: $request specified for destination: Input].
Any help on how to pass multiple values would so be appreciated.
I'm trying to use cloud formation (YAML template file) to deploy a CloudFront Function in my stack. How do I specify the FunctionCode (AWS docs) property for my CloudFront Function?
AddHTMLPostfixFunction:
Type: AWS::CloudFront::Function
Properties:
Name: !Sub "${ApplicationName}-add-html-postfix"
AutoPublish: true
FunctionCode: "---> Path to my .js-file? <---"
FunctionConfig:
Comment: "Adds .html postfix to viewer requests"
Runtime: cloudfront-js-1.0
I'm unable to find any examples of this, other than the CLI commands that has been documented from AWS.
It's possible to use inline code!
AddHTMLPostfixFunction:
Type: AWS::CloudFront::Function
Properties:
Name: !Sub "${ApplicationName}-add-html-postfix"
AutoPublish: true
FunctionCode: |
function handler(event) {
var hasExtension = /(.+)\.[a-zA-Z0-9]{2,5}$/
var request = event.request
var uri = request.uri
// If the request does not have any extension, add '.html'
if (uri && !uri.match(hasExtension)) {
request.uri = `${uri}.html`
}
return request
}
FunctionConfig:
Comment: "Adds .html postfix to viewer requests"
Runtime: cloudfront-js-1.0
I am trying to implement the below calls:
POST https://host/sessions
DELETE https://host/sessions/{session_id}
The POST call is to establish a session, the DELETE call is to log out an established session.
So, in the YAML file, how to have an empty base path? It's currently a slash in the YAML file as it's a required filed, but the slash is redundant. Any idea? Thanks.
swagger: '2.0'
info:
version: '0.0.1'
title: authenticate
#description: To be provided
# #termsOfService:To be provided
contact:
name: test
basePath: /sessions
paths:
/:
post:
summary: eatablish a session
description: sessions is a collection.This POST creates a new session in the sessions collection and the name of the session returned by this command is the session token.
consumes:
- "application/json"
parameters:
- in: header
name: user_name
type: string
required: true
- in: header
name: password
type: string
required: true
responses:
200:
description: establish a session successfully
400:
$ref: "#/responses/BadRequest"
500:
description: unexpected error
schema:
$ref: '#/definitions/errorModel'
/{session_id}:
delete:
summary: log out
description: use sessionid to log out an established session.
produces:
- application/json
parameters:
- in: path
name: session_id
type: string
required: true
responses:
200:
description: log out a session successfully
400:
$ref: "#/responses/BadRequest"
500:
description: unexpected error
schema:
$ref: '#/definitions/errorModel'
Swagger defines
A relative path to an individual endpoint. The field name MUST begin with a forward slash (/).
Therefore, the slash is required and you can't have an empty path.
I test my Api with DREDD against it's specification (written in Openapi3 considering, painfull limitations of Support by Dredd considered). No I have one endpoint, which produces CSV-data if the Accept-header is set so.
'/my-endpoint':
summary: ...
description: ...
get:
# parameters:
# -
# in: header
# name: Accept
# description: "Response format: application/json or text/csv"
# example: "text/csv"
responses:
'200':
description: ...
content:
text/csv:
schema:
type: string
example:
summary: 'csv table'
value: 'cell1, cell2'
When I run the test with Dredd the test fails with
expected:
headers:
body:
[
{
"key": "summary",
"value": "csv table"
},
{
"key": "value",
"value": "cell1, cell2"
}
]
statusCode: 200
Clearly there is something misunderstood and Dredd expects still JSON. Also the API is not told to produce the CSV Version. If I commit in the Accept header in the code abvoe I get the very same result - the expecetd result above and as actual result the JSON version of the my-endpoint-data and also ad warning:
warn: API description parser warning in .../tmp/transformed.specs.yml: 'Parameter Object' 'name' in location 'header' should not be 'Accept', 'Content-Type' or 'Authorization'
I read here and here: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers, use the corresponding OpenAPI keywords - but what are they? According to this and this page it seems to be enough to specify a response of the given type but that is clearly not enough to tell Dredd to produce such a header.
You got an error because the value of the example key is meant to be a literal example value. So in your case it's treated as an object with the summary and value properties.
Change your definition to:
content:
text/csv:
schema:
type: string
example: 'cell1, cell2'
Or if you want to provide a summary/description for an example, use examples instead:
content:
text/csv:
schema:
type: string
examples:
csv table:
summary: A CSV table with 2 cells
value: 'cell1, cell2'
Problem
The issue concerns swagger codegen and using multiple files to define specs.
I have two REST APIs with two different files specs1.yml and specs2.yml.
These specs have some models/schemas/definitions (I use swagger 2.0) in common.
I'd like to factorize these definitions in a core.yml file.
I can then reference these in specs1 and specs2.
The issue is that swagger codegen generates these models as part of specs1 and specs2. What I'd like is processing the core.yml file, generating classes in a core package, and then having the specs1/2 generated classes referencing the classes in the core package when it's a common one.
Technical Stack
Maven / Java / JAXRS-CXF REST API
Maven 3.6.0
Java 1.8.0_201
swagger-jaxrs 1.5.16
CXF 3.1.14
swagger-codegen-maven-plugin 2.4.7
Code Example
Swagger Specs YML
I have a tag named e.g. "Super Tag" in my swagger specs definition.
Multiple endpoints are regrouped under that tag. For the sake of a minimal PoC of my issue, let's go with one endpoint:
specs1.yml
swagger: "2.0"
tags:
- name: "Super Tag"
x-core-imports: [ErrorResponse] # Trying this at tag level
x-imports: [ABody] # Trying this at tag level
paths:
/someEndpointPath:
post:
x-core-imports: [ErrorResponse] # --> import bla.core.api.models.ErrorResponse
x-imports: [ABody] # --> import bla.project.api.models.ABody
tags:
- "Super Tag"
operationId: postToSomeEndpoint
consumes:
- application/json
produces:
- application/json
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/ABody' # This model is defined in this file
responses:
204:
description: "Successful response"
400:
description: "Bad request error"
schema:
$ref: '../CORE.yml#/definitions/_ErrorResponse'
# I'm importing this model definition from another file
definitions:
ABody:
type: object
field:
type: string
Swagger Codegen Debugging
I tried seeing where the vendor extensions would be added with regards to imports: [{ "import": ... }] (which is what's read from the api.mustache template, see below)
> java -DdebugSupportingFiles -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i specs.yml -l java > result.json
I can see
result.json
"apiInfo" : {
"apis" : { [
"parent" : [ ],
"generatorClass" : "io.swagger.codegen.languages.JavaClientCodegen",
"supportJava6" : false,
"sortParamsByRequiredFlag" : true,
"groupId" : "io.swagger",
"invokerPackage" : "io.swagger.client",
"classVarName" : "superTag",
"developerEmail" : "apiteam#swagger.io",
"generateModelDocs" : true,
"hasImport" : true,
"generateModelTests" : true,
"generateApiTests" : true,
"classFilename" : "SuperTagApi",
"usePlayWS" : false,
"generateModels" : true,
"serializableModel" : false,
"playVersion" : "play25",
"inputSpec" : "specs.yml",
"artifactUrl" : "https://github.com/swagger-api/swagger-codegen",
"developerOrganization" : "Swagger",
"baseName" : "SuperTag",
"package" : "io.swagger.client.api",
"imports" : [ {
"import" : "io.swagger.client.model.ABody"
}, {
"import" : "io.swagger.client.model.ErrorResponse"
} ]
...
] }
}
Swagger Templates
We can see in the api.mustache template
package {{package}};
{{#imports}}import {{import}};
{{/imports}}
I'm using the maven swagger codegen plugin with the following options:
<modelPackage>com.mysite.myproject.api.models</modelPackage>
<apiPackage>com.mysite.myproject.api</apiPackage>
So in my generated java class I will get:
SuperTagApi.class
package com.mysite.myproject.api;
import com.mysite.myproject.api.models.ErrorResponse;
import com.mysite.myproject.api.models.ABody;
What I'd like to do is have a means to tell swaggercodegen that I want one class imported as it is now, but the second imported from another package.
To do that, my idea was using vendor extensions (as you can see above) and manually list the classes that I want imported from a given package (that will actually be generated from the CORE.yml file) and the ones that are defined in my specs.yml where I want the original generated package name.
I tried adding x-core-imports vendor-extension to multiple different places trying to get access to them. None put them at the same level as the imports: [{ "import": ... }] section of the result.json... This is because different endpoints/methods are regrouped under the same file when their tag is identical.
I modified my api.mustache like so:
{{^vendorExtensions.x-imports}}
{{#imports}}import {{import}};
{{/imports}}
{{/vendorExtensions.x-imports}}
{{#vendorExtensions.x-imports}}
{{#vendorExtensions.x-core-imports}}
import com.mysite.core.api.models.{{.}};
{{/vendorExtensions.x-core-imports}}
import com.mysite.myproject.api.models.{{.}};
{{/vendorExtensions.x-imports}}
Do you know at which level in the yml file I have to put my vendor extensions to be able to access them from api.mustache? (Without modifying swagger codegen, just modifying templates and yml specs files)