How to parameterize the API base path in OpenAPI (Swagger)?

11,375

Solution 1

Parameterized base paths are now supported in OpenAPI 3.0, using server variables:

openapi: 3.0.0
...

servers:
  - url: https://my.api.com/id/{number}
    variables:
      number:
        default: '-1'

Note that server variables MUST have a default value - it will be used if the client does not supply a value.

For details, see:

Solution 2

I don't think basePath allows variables.

For your case, you don't need to use basePath. You can simply put /id/{idnumber} in the URL path. For example:

    "/pet/{petId}": {
Share:
11,375
Rad4
Author by

Rad4

Updated on July 25, 2022

Comments

  • Rad4
    Rad4 over 1 year

    I have an URL like this:

    /id/{idnumber}/status
    

    In this URL, /id/{idnumber} is the API base path, and /status is the resource.


    I know that OpenAPI (Swagger) allows parameters in paths, like so:

    paths:
      /id/{number}/status:
    

    but this is not what I need, because /id/{idnumber} is the base path and not part of the resoruce path.

    Is there any way to have a parameter in the base path?

    host: my.api.com
    basePath: /id/{idnumber}   # <---
    
    paths:
      /status:
    
  • Rad4
    Rad4 over 7 years
    But my scenario is so obvious that I have to use only basepath variable.I want to know how to do it in Swagger.
  • Ben Randall
    Ben Randall over 7 years
    Sorry @Rad4, You just can't use variables in basePath. You would likely have to use /id as your basepath and then just have {idnumber}/status as your operation.
  • ennth
    ennth over 2 years
    Can you use /id/{number} as the server url (basePath in swagger 2.0)? our swagger 2.0 just used /id/{number} for basepath so any env like dev/prod/qa would set the base url - does the full qualified domain name (FQDN) have to be defined now in openapi 3.0?
  • petertc
    petertc over 1 year
    not supported by postman