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

Question

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:

Helen · Accepted Answer · 2022-09-13 06:55:18Z

16

Parameterized base paths are supported in OpenAPI 3.x, 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:

Server Object and Server Variable Object sections of the the OpenAPI 3.0 Specification
API Server and Base URL on swagger.io

edited Sep 13, 2022 at 6:55

answered Mar 15, 2018 at 10:44

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

PainIsAMaster Over a year ago

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 Over a year ago

not supported by postman

William Cheng · Accepted Answer · 2016-02-23 06:51:19Z

1

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}": {

answered Feb 23, 2016 at 6:51

William Cheng

10.9k5 gold badges57 silver badges85 bronze badges

2 Comments

Rad4 Over a year ago

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 Over a year ago

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.

Collectives™ on Stack Overflow

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

2 Answers 2

2 Comments

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related