so am exploring swagger and how its documentation works in a yaml file, tried it before with the @swagger in the controller file and they worked fine, but when i tried to switch them to a yaml file for them to be more organized, besides from get patch, they don't want to work as it tells me that the properties in the model are required: true.

let's take the exemple of a PATCH request, i have a property named isDeleted that is false by default and required and it will be changed to isDeleted: true when called but it won't work as swagger tells me that the path isDeleted is required but when i change the required to false it works but i don't want that PS: in postman they work perfectly only in swagger i have this problem.

Swagger Config File:

import path from 'path';
export const swaggerDefinition = {
    openapi: '3.0.0',
    info: {
        title: 'test',
        version: '1.0.0',
        description: 'test ',

        contact: {
            name: 'ymena ',
        },
    },
    servers: [
        {
            url: 'http://localhost:5000',
            description: 'Development server',
        },
    ],
    components: {
        securitySchemes: {
            bearerAuth: {
                type: 'http',
                scheme: 'bearer',
                bearerFormat: 'JWT',
            },
        },
    },

};
export const swaggerOptions = {
    swaggerDefinition,
    apis: ['./src/resources/**/docs/*.yaml'],
};

swagger in app file:

        this.express.use(
            '/docs',
            SwaggerUI.serve,
            SwaggerUI.setup(swaggerJSDoc(swaggerOptions)),
        );

this is the yaml File :

paths:
    /api/order/deleteOrder/{orderId}:
        patch:
            tags:
                - Order
            summary: change the status of a certain order
            produces:
                - application/json
            security:
                - bearerAuth: []
            parameters:
                - name: orderId
                  in: path
                  description: path parameter takes the order id to be deleted
                  required: true
                  schema:
                      type: string
                      example: 6352e63e29c4c5439a435d56

                - name: isDeleted
                  in: body
                  description: will change the order status from false to true 
                  required: true
                  schema:
                      type: object
                      properties:
                          isDeleted:
                              type: boolean

            responses:
                200:
                    description: successfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/definitions/sucesssDeleteOrderResponse'

                500:
                    description: Unsuccessfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/definitions/FailureDeleteOrderResponse'

definitions:
    deleteOrder:
        type: object
        properties:
            isDeleted:
                type: boolean

    sucesssDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Orders status changed successfully'
            statut:
                type: number
                default: 200

    FailureDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Failed to change status order'
            statut:
                type: number
                default: 500

and this is the property in the model:

isDeleted: {
            type: Boolean,
            default: false,
            required: true,
        },

and below you'll find swagger :

the reponse i get:

Thank you very much for your time.

CodePudding user response：

You're mixing up OpenAPI 3.0 and 2.0 syntax in your annotations. Since you use openapi: '3.0.0':

1. The request body should be defined using the requestBody keyword instead of a body parameter.
2. Schemas should be in the components.schemas section instead of definitions.
3. Operations don't need the produces keyword. Response media type is defined by responses.<code>.content.<media-type>.

The correct version is:

paths:
    /api/order/deleteOrder/{orderId}:
        patch:
            tags:
                - Order
            summary: change the status of a certain order
            security:
                - bearerAuth: []
            parameters:
                - name: orderId
                  in: path
                  description: path parameter takes the order id to be deleted
                  required: true
                  schema:
                      type: string
                      example: 6352e63e29c4c5439a435d56

            requestBody:  # <---------
              description: will change the order status from false to true
              required: true
              content:
                application/json:
                  schema:
                      type: object
                      properties:
                          isDeleted:
                              type: boolean

            responses:
                200:
                    description: successfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/sucesssDeleteOrderResponse'

                500:
                    description: Unsuccessfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FailureDeleteOrderResponse'

components:  # <---------
  schemas:   # <---------

    deleteOrder:
        type: object
        properties:
            isDeleted:
                type: boolean

    sucesssDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Orders status changed successfully'
            statut:
                type: number
                default: 200

    FailureDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Failed to change status order'
            statut:
                type: number
                default: 500