My question:
I’ve created a new API definition in API Designer with two paths ‘/{userid}’ and ‘/search’. Both take the same path position where one is a variable and the other is a fixed value.
The spec I’m using is the following.
openapi: 3.0.0
info:
version: '0.1.0'
title: 'TestAPI'
license:
name: MIT
servers:
- url: 'localhost:3000'
paths:
/search:
get:
summary: 'search'
operationId: search
tags:
- user
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/{userid}:
get:
summary: 'userId'
operationId: listUser
tags:
- user
parameters:
- in: path
name: userid
schema:
type: string
required: true
description: Unique identifier for the user.
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
The Designer finds no shema issues.
When I generate the collection for the first time from this API definition using the ‘Generate Collection’ button, I find that a collection is generated with the two requests correctly.
This is good and expected!
When I update the summary attribute for each endpoint definition, save the Definition and then validate the Collection, I find both endpoints are shown to have changes and both collections are updated properly when apply changes.
/search:
get:
summary: 'search users'
...
...
...
/{userid}:
get:
summary: 'getByUserId'
This works as expected.
ISSUE:
What I find being an issue is if remove the ‘/search’ endpoint, save definition, and validate collection, I see ‘sync collection to schema’ window indicate that there are changes to both existing requests as it’s seeing both being compared against the ‘/{userid}’ request in the collection.
openapi: 3.0.0
info:
version: '0.1.0'
title: 'TestAPI'
license:
name: MIT
servers:
- url: 'localhost:3000'
paths:
/{userid}:
get:
summary: 'getByUserId'
operationId: listUser
tags:
- user
parameters:
- in: path
name: userid
schema:
type: string
required: true
description: Unique identifier for the user.
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
This is not expected.
If I were to instead remove the ‘/{userid}’ path definition, save, and validate collection, I see that the Sync Collection to Schema window shows expected outcome of the ‘/{userid}’ request is to be removed from the collection.
openapi: 3.0.0
info:
version: '0.1.0'
title: 'TestAPI'
license:
name: MIT
servers:
- url: 'localhost:3000'
paths:
/search:
get:
summary: 'search'
operationId: search
tags:
- user
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
This scenario is expected.
MAIN ISSUE Encountered:
The other issue is if I only have the ‘/search’ path definition in the API Designer and collection (both being synced properly like below.
openapi: 3.0.0
info:
version: '0.1.0'
title: 'TestAPI'
license:
name: MIT
servers:
- url: 'localhost:3000'
paths:
/search:
get:
summary: 'search'
operationId: search
tags:
- user
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
Then I want to add an endpoint path that is a variable at the same level as where search is already defined. Then I save the definition, and validate the collection with the definition, I find that the validation says everything is good.
openapi: 3.0.0
info:
version: '0.1.0'
title: 'TestAPI'
license:
name: MIT
servers:
- url: 'localhost:3000'
paths:
/search:
get:
summary: 'search'
operationId: search
tags:
- user
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/{userid}:
get:
summary: 'getByUserId'
operationId: listUser
tags:
- user
parameters:
- in: path
name: userid
schema:
type: string
required: true
description: Unique identifier for the user.
responses:
'200':
description: 'Sample response: Details about a user by ID'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
Clicking validate will indicate still valid
I would expect the validate of collection against updated API definition to indicate a new endpoint of ‘/{userid}’ and allow me to add it just as if I were to generate a new collection where both ‘/search’ and ‘/{userid}’ were both defined and generated successfully.
I have opened a Github ticket for this issue as well that can be found here Schema Validation not working when Path Templating and Fixed Paths in same path position · Issue #11196 · postmanlabs/postman-app-support · GitHub