I have a swagger fragment like this
responses: { '200': { description: 'Agent data', schema: { type: object, properties: { agentRecord: { type: object, properties: { username: { type: string }, vpnname: { type: string }, google_id: { type: string } } }, googleRecord: { type: object }, agentACLs: { type: object } } } }, default: { description: 'Unexpected error', schema: { $ref: '#/definitions/Error' } } }
but I want it to be like
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Success"
}
},
How to convert text style from (1) to (2)? I couldn't find any solution in the internet.
UPDATE
I am not developing a program I just want to eliminate handy work and convert one text style to text with another style.
Paste your YAML into http://editor.swagger.io and then select the menu item Edit > Convert to YAML. This will pretty-print your YAML.
Related
I'm using joi-to-swagger and swagger-ui-express and I'm really struggling to find out how to get this schema to show up correctly. It's getting ignored in all scenarios and I can't find the documentation I need to correctly use the schema.
My file:
import j2s from 'joi-to-swagger'
import joi from 'joi'
import swaggerUi from 'swagger-ui-express'
const myJoiSchema = joi
.object({
text: joi.string().max(100).required(),
})
.required()
const schema = j2s(myJoiSchema).swagger
const swaggerDoc = {
swagger: '2.0',
info: {
title: 'title',
version: '1.0',
},
paths: {
'/my-url': {
post: {
summary: 'my api',
// consumes: 'application/json',
// parameters: mySchema, didn't work
requestBody: {
required: true,
schema: {
$ref: '#/components/schemas/mySchema',
},
},
},
},
},
components: {
schemas: {
mySchema: schema,
},
},
}
router.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc))
the schema that is produced for value schema is:
{
type: 'object',
properties: {
text: { type: 'string', maxLength: 100 },
},
required: [ 'text' ],
additionalProperties: false
}
How is the schema supposed to be properly used in the swagger doc? It might be special with swagger-ui-express but I can't confirm I've tested it correctly.
I have this route which can return one of these two different DTOs:
#Get()
#ApiQuery({ name: 'legacy', description: "'Y' to get houses legacy" })
async findAllHouses(
#Query('legacy') legacy: string,
): Promise<HousesDto[] | HousesLegacyDto[]> {
...
}
I want to display both of these ResponseDTOs in swagger.
I've tried this decorator:
#ApiOkResponse({
schema: { oneOf: refs(HousesDto, HousesLegacyDto) },
})
// OR
#ApiOkResponse({
schema: {
oneOf: [
{ $ref: getSchemaPath(HousesDto) },
{ $ref: getSchemaPath(HousesLegacyDto) },
],
},
})
with #ApiExtraModels() on top of DTO classes and #ApiProperty() on each properties.
But I still get empty objects in Swagger and I suppose it would not have even taken array types in consideration.
How can I display both of these schemas properly?
Seems to me like a lot of very obscure solutions have been posted here and there, so I will try to clarify what needs to be done.
You have two DTOs:
export class SomeStatusDto {
#ApiProperty({
description: 'Id',
example: 1,
})
#IsNumber()
id: number;
#ApiProperty({
description: 'Status',
example: 'in_progress',
})
#IsString()
status: string;
}
export class ErrorStatusDto {
#ApiProperty({
description: 'Id',
example: 1,
})
#IsNumber()
id: number;
#ApiProperty({
description: 'Error',
example: 'Some error string',
})
#IsString()
error: string;
}
Then you have your controller:
#UseGuards(AccountTypesGuard)
#ApiOperation({ summary: 'Get status of...' })
#Get('status')
#ApiExtraModels(SomeStatusDto, ErrorStatusDto)
#ApiOkResponse({
schema: { anyOf: refs(SomeStatusDto, ErrorStatusDto) },
})
async getPullStatus(
#Request() req,
#Param('id', ParseIntPipe) someId: number,
): Promise<SomeStatusDto | ErrorStatusDto> {
// check if someId belongs to user
const idBelongsToUser = await this.myService.validateSomeId(
req.user.id,
someId,
);
if (!idBelongsToUser) {
throw new ForbiddenException(
`SomeId does not belong to user (someId=${someId}, userId=${req.user.id})`,
);
}
const key = `status-${someId}`;
const response = await this.redisService.getByKey(key);
return response ? response : {};
}
Note the solution below. You need to reference the DTOs as #ApiExtraModels() and then you can add them as anyOf: refs(...) in your schema.
#ApiExtraModels(SomeStatusDto, ErrorStatusDto)
#ApiOkResponse({
schema: { anyOf: refs(SomeStatusDto, ErrorStatusDto) },
})
Hope this helps somebody :)
so I encountered a similar issue and this is how you could get the output shown in the image above.
Using the #ApiResponse decorator you could set the two responses using the examples property, try the code sample below
#ApiResponse({
status: 200,
description: 'Successful response',
content: {
'application/json': {
examples: {
HousesDto: { value: HousesDto },
HousesLegacyDto: { value: HousesLegacyDto },
},
},
},
})
I use fastify-swagger (https://github.com/fastify/fastify-swagger) for my fastify server. I also use the JSEND (https://github.com/omniti-labs/jsend) standard, which means that the data returned may be different with the same response code 200.
I do not understand how I can build a scheme for multiple response data with a single 200 code.
The Open Api 3 specification (which fastify-swagger supports) seems to allow you to describe this (https://swagger.io/specification /)
I tried this, but it doesn't work. The response from the server is simply not validated and comes as is.
const chema_1 = {
description: 'description',
type: 'object',
properties: {
status: {
type: 'string',
description: 'string'
},
}
}
const chema_2 = {
description: 'description',
type: 'object',
properties: {
body: {
type: 'string',
description: 'number'
},
}
}
fastify.route({
method: 'GET',
url: '/coursesList',
schema: {
response: {
'200': {
oneOf: [
chema_1,
chema_2,
]
}
}
},
handler: async (request, reply) => {
// handler
}
})
I also tried this. Same behavior:
const chema_1 = {
response: {
'200': {
description: 'description',
type: 'object',
properties: {
status: {
type: 'string',
description: 'string'
},
}
}
}
}
const chema_2 = {
response: {
'200': {
description: 'description',
type: 'object',
properties: {
body: {
type: 'string',
description: 'number'
},
}
}
}
}
fastify.route({
method: 'GET',
url: '/coursesList',
schema: {
oneOf: [
chema_1,
chema_2,
]
},
handler: async (request, reply) => {
// handler
}
})
There are no such examples in the documentation. Maybe someone can help me?
I am newbie to openapi . I need some help in writing open api yml 3.0
for below response format
{
“Details”: {
“detail1”: [
{
"id": “idvalue”1,
“Info”: {
“Testinfo1”: "1.0.0",
“Testinfo2”: "2.0.0"
}
}
],
“Detail2”: [
{
"id": “idvalue2”,
“Info”: {
“Testinfo3”: "1.0.0",
“Testinfo4”: "2.0.0" }
}
],
"Detail3”: [
{
“First name”: “firstName,
“Lastname: “last”Name,
“Address”: “address”,
“Dependents”: []
}
]
},
"links": {
"self": {
"href": “some url”
}
}
}
detail1, detail2, detail3 could be different object types or same object types
and there can be any no of details .
I am struck at below points
how can i represent map open api
how to represent multiple object types with in map.
Check this below YAML snap
DetailsSchemaElement:
type: object
properties:
Details:
type: object
properties:
detail1:
type: array
items:
properties:
id:
type: string
Info:
type: object
properties:
Testinfo1:
type: string
Testinfo2:
type: string
Detail2:
type: array
items:
properties:
id:
type: string
Info:
type: object
properties:
Testinfo4:
type: string
Testinfo3:
type: string
Detail3:
type: array
items:
properties:
First-name:
type: string
Address:
type: string
Dependents:
type: array
items:
type: string
Lastname:
type: string
links:
type: object
properties:
self:
type: object
properties:
href:
type: string
The response example I would like to put in the yaml file is something like:
{
"name": "Element",
"schema": {
"properties": {
"id": {
"type": "string"
},
"extension": {
"type": "array",
"items": {
"$ref": "#/definitions/Extension"
}
}
}
}
}
And the ymal of this example will be:
responses:
200:
description: "successful operation, return the definition of the resource type in the body"
examples:
application/json:
name: Element
schema:
properties:
id:
type: string
extension:
type: array
items:
$ref: '#/definitions/Extension'
As you can see the last line is "$ref: '#/definitions/Extension'", thus Swagger thinks it is a reference which it can not find anywhere in the ymal file.
Is it possible to escape this to get way from being a reference?
This is a bug in Swagger Editor and UI.
As a workaround, define a schema for your response and use a schema example instead. Schema examples are displayed fine in Swagger Editor 3.6.6 and Swagger UI 3.17.5. You might still see a $ref resolution error in the editor, but at least the example is displayed correctly.
responses:
200:
description: "successful operation, return the definition of the resource type in the body"
schema:
$ref: '#/definitions/MyResponseSchema'
definitions:
MyResponseSchema:
type: object
properties:
name:
type: string
schema:
type: object
properties:
...
example: # <------------
name: Element
schema:
properties:
id:
type: string
extension:
type: array
items:
$ref: '#/definitions/Extension'