Rswag: Readme for OA 3

[martio]

There is an error in the readme:

    'v2/swagger.yaml' => {
      openapi: '3.0.0',
      info: {
        title: 'API V2',
        version: 'v2',
        description: 'This is the second version of my API'
      },
      basePath: '/api/v2'
    }

In OA 3 instead of basePath is servers.

      servers: [
        {url: 'http://localhost/api/v2', description: 'Development server (uses test data)'},
        {url: 'http://domain.com/api/v2', description: 'Production server (uses live data)'}
      ]

Source: https://swagger.io/docs/specification/api-host-and-base-path/

In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description.

[BookOfGreg]

basePath from the document does get re-written into path. Host and Schemes are the bits that need to be converted for OpenAPI3.

Example output from current rswag:

  "host": "my.host.com",
  "schemes": [
    "https"
  ],
  "paths": {
    "/basePath/path/{path_params}": {
      "get": {

[heldersantosmoreira]

So what should one use? basePath or servers?

[BookOfGreg]

Both. basePath will be concatenated on and wont appear in final doc. servers need to be there for OpenAPI3 when this gem starts supporting it.

[martio]

It does not work...

 config.swagger_docs = {
    'v1/swagger.yaml' => {
      openapi: '3.0.1',
      info: {
        title: 'Example API',
        version: 'v1'
      },
      paths: {},
      basePath: '/api/v1',
      servers: [
        {url: 'https://dev.example.pl', description: 'Development server (uses test data)'},
        {url: 'https://example.pl', description: 'Production server (uses live data)'}
      ]
    }
  }

and output:

  openapi: 3.0.1
  info:
    title: Example API
    version: v1
  paths:
    "/hello":

  (...)

  basePath: "/api/v1"
  servers:
  - url: https://dev.example.pl
    description: Development server (uses test data)
  - url: https://example.pl
    description: Production server (uses live data)

Contains "basePath that should not be found there...

[malkovro]

It seems like rswag is expecting you to choose one syntax or the other.
As you started describing the servers, it did not pick the basePath.
If you want to keep using basePath, enter the servers info in the key schemes.

As a ref, here is what's doing the formatter:
https://github.com/rswag/rswag/blob/7ceedab4cb7788ab6b86b96bd2d8f2419e11ebbb/rswag-specs/lib/rswag/specs/swagger_formatter.rb#L156-L169