feathersjs-ecosystem / feathers-swagger

Add documentation to your FeatherJS services and feed them to Swagger UI.
MIT License
225 stars 63 forks source link

How to enable the jsonEditor for the request body? #211

Closed SeverinNovack closed 4 years ago

SeverinNovack commented 4 years ago

I have completed my implementation of the swagger documentation und made all my definitions. My swagger instance:

app.configure(swagger({
    docsPath: '/docs',
    uiIndex: path.join(__dirname, '/../public/docs.html'),

    specs: {
       info: {
            title: 'The dokumentation of the authentication and authorization server',
            // description: 'A description',
            version: '1.0.0',
        },
        securityDefinitions: {
            APIKeyHeader: {
                type: 'apiKey',
                in: 'header',
                name: 'x-access-token'
            }
        },
        definitions: {
            Error: {
                title: 'Error',
                description: 'The standard error layout',
                type: 'object',
                properties: {
                    errorCode: {
                        type: 'integer',
                        description: 'Unique number to find the error in the code',
                        example: 10199
                    },
                    userMessage: {
                        type: 'string',
                        description: 'Message shown in the frontend'
                    },
                    developerMessage: {
                        type: 'string',
                        description: 'Message with further info for the developers'
                    },
                }
            },
        }
    }
})
)

And here an example for an operation on a service:

const doc = {
    operations: {
      create: {
        security: [{
          APIKeyHeader: []
        }],
        description: 'Creates a customer',
        parameters: [
          {
            required: true,
            in: 'body',
            schema: {
              type: 'object',
              properties: {
                name: {
                  type: 'string',
                  description: 'the name of the customer to be created',
                  example: 'XXX',
                  required: true
                },
                groups: {
                  type: 'array',
                  description: 'the groups that the customer should be in ',
                  items: {
                    type: 'string',
                    description: 'customer id',
                    example: uuid()
                  }
                }
              }
            }
          }
        ],
        responses: {
          201: {
            description: 'created',
            schema: { $ref: `#/definitions/CreateCustomerResponse` }
          },
          400: {
            description: 'bad request',
            schema: { $ref: `#/definitions/Error` }
          },
          401: {
            description: 'unauthorized',
            schema: { $ref: `#/definitions/Error` }
          },
          500: {
            description: 'internal error',
            schema: { $ref: `#/definitions/Error` }
          }
        }
      },
   }
}

When I try to edit the example values in the "try it out" nothing happens. I followed the answer of this and added it into my docs.html but it did not change anything. Is there a specific way to enable the editor? I also wasn't able to find where to disabled the validorUrl in the documentation, where do I disable that?

Mairu commented 4 years ago

Hi, so the problem why you can't edit in try out mode is because you have no name for the parameter. If you use the following, it will work.

parameters: [
          {
            required: true,
            name: 'body', // this line is added
            in: 'body',
            schema: {
              type: 'object',

For the validator, I think that has to be changed when initializing SwaggerUIBundle in the docs.html. The documentation mentions to set validatorUrl to null to disable the validator.

SeverinNovack commented 4 years ago

That is exactly the answer I needed, both of your answers where right. Thank you very much for your time.