scottie1984 / swagger-ui-express

Adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app.
MIT License
1.42k stars 225 forks source link

SwaggerDefinition is not parsed correctly #230

Closed gtamas closed 2 years ago

gtamas commented 3 years ago

I have this in my swaggerDefinition:

    info: {
                openapi: "3.0.3",
                title: 'something',                 
                description: 'API',
                version: '2.0.0',
            },
            host: "127.0.0.1:3000",
            basePath: "/",
            security: {
                "ApiKeyAuth": []
            },
            components: {
                securitySchemes: {
                    ApiKeyAuth: {
                        type: "apiKey",
                        name: "accessToken",
                        in: "header",
                        description: "Access token based security"
                    }
                }

            },
            servers: [
                {
                    "url": "http://127.0.0.1:3000",
                    "description": "local server"
                },
                {
                    "url": "https://some.other.url",
                    "description": "Dev server"
                }                     
            ]

But when I click Authorize in swagger UI, it just prints an empty popup.
The servers section also doesn't get populated. There should be drop-down menu with the available servers.

The swaggerDefinition object is an OpenAPI Object, correct? https://swagger.io/specification/#oasObject

Or is it not?

I'm using swagger-jsdoc and they say swaggerDefinition should be an oasObject. But obviously that doesn't work. So what is the correct input here?

gtamas commented 3 years ago

Or does this package only support OpenAPI 2.x (Swagger) Schema? Is OpenAPI 3.x supported? @scottie1984 https://github.com/scottie1984/swagger-ui-express/issues/96

You say it supports 3.x, but openapi 3.x syntax doesn't seem to be recognised. I'm confused. Which one should I use?

The following works, but this is Swagger 2.x

 swaggerDefinition: {
            info: {
                openapi: "3.0.3",
                title: "sdsss"                 
                description: 'API',
                version: '1.0.0', // Version (required)
            },
            host: "127.0.0.1:3000",
            basePath: "/",
            consumes: ["application/x-www-form-urlencoded"],
            produces: ["application/json"],
            security: {
                "ApiKeyAuth": []
            },
            securityDefinitions: {
                ApiKeyAuth: {
                    type: "apiKey",
                    name: "accessToken",
                    in: "header",
                    description: "Access token based security"
                }
            }
        },
JoffrayBillon commented 3 years ago

@gtamas Swagger structure is made with the openapi tag (or swagger for openapi 2) out of the info object. https://swagger.io/docs/specification/basic-structure/ https://github.com/Surnet/swagger-jsdoc/blob/master/docs/GETTING-STARTED.md Following the docs your code should look like that:

openapi: "3.0.3",
info: {
  title: 'something',                 
  description: 'API',
  version: '2.0.0',
}

As you use swagger-jsdoc your code should look like that for oapi3:

swaggerDefinition: {
  openapi: '3.0.2',
  info: {
    title: 'something',            
    description: 'API',
    version: '1.0.0',
  },
  servers: [
  {
    "url": "http://127.0.0.1:3000",
     "description": "local server"
   },
   {
     "url": "https://some.other.url",
      "description": "Dev server"
    }                     
  ]
},

Also think remove the basePath and host tags they don't exist anymore in oapi3 and refers to the docs.