Apicurio-studio: Warning is not correct when "-" exists in path parameter

[yuanhuiliu]

After importing the attached API design which has path parameter "xxx-yyy", warning 'Path Parameter "ticket-id" not found in path template' is promoted. Actually, path parameter "ticket-id" exists. The screenshot is as follows:

[yuanhuiliu]

Add the sample api design.
api sample.txt

[jmini]

Could reproduce it with:

openapi: 3.0.1
info:
    title: Todo Backend
    version: '1.0'
paths:
    '/api/{todo-id}':
        get:
            parameters:
                -
                    example: 42
                    name: todo-id
                    description: The id of the todo
                    schema:
                        format: int64
                        type: integer
                    in: path
                    required: true
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Todo'
                    description: The requested Todo
            operationId: todoGetOne
            summary: Get one todo
        delete:
            parameters:
                -
                    example: 42
                    name: todo-id
                    description: The id of the todo
                    schema:
                        format: int64
                        type: integer
                    in: path
                    required: true
            responses:
                '204':
                    description: No content
            operationId: todoDeleteOne
            summary: Delete one todo
        patch:
            requestBody:
                description: The todo to update
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Todo'
            parameters:
                -
                    example: 42
                    name: todo-id
                    description: The id of the todo
                    schema:
                        format: int64
                        type: integer
                    in: path
                    required: true
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Todo'
                    description: The updated Todo
            operationId: todoUpdate
            summary: Update an existing todo
components:
    schemas:
        Todo:
            description: Object representing a Todo
            type: object
            properties:
                id:
                    format: int64
                    description: id of the entity
                    type: integer
                    example: 42
                title:
                    description: title of the todo
                    type: string
                    example: My task
                completed:
                    description: whether the todo is completed or not
                    type: boolean
                    example: false
                url:
                    description: url associated with the todo
                    type: string
                order:
                    format: int32
                    description: order in the priority list
                    type: integer
                    example: 10

[EricWittmann]

Can anyone find any documentation about what is allowed and what is not? I didn't see anything in the OpenAPI spec, but perhaps there is something I missed...or perhaps there is something documented elsewhere that defines a pattern for a path parameter?

[yuanhuiliu]

I tried to find anything about pattern of path parameter in OpenAPI spec but find nothing :(

[jmini]

I have opened https://github.com/OAI/OpenAPI-Specification/issues/1969 to see if there is a restriction/recommendation.

[EricWittmann]

Answer from the OpenAPI spec is:

OAS 3.0 imposes no restrictions on parameter names, whether in: path or not. Even the empty string should be valid.

That said, use of { and } characters in path parameter names could lead to confusion, so you might want to avoid this.

So the implication here is that any rules we have implemented for validating parameter names should be disabled for the "Spec Only" validation profile. Any additional rules we want to include are totally fine (obviously) but should not be enabled when performing spec validation.

[EricWittmann]

The problem is that this makes it tricky in the UI. The form used to create a parameter has a regex associated with it that will prevent users from entering certain characters. But depending on the validation profile being used, that regex might be inconsistent with one or more validation rule. There probably isn't really anything sensible that can be done about that. Typically my view is that the UI should only prevent users from doing something that will result in an illegal (not invalid) document. So my feeling would actually be that we should loosen up the UI restrictions and let validation handle things.

Thoughts?

[jmini]

In Apicurio, the feature I like the most is the possibility to use the UI and to always have the possibility to edit the OpenAPI specification as Yaml. This is really great (but might not represent how the tool is used by the majority of users).

---

my feeling would actually be that we should loosen up the UI restrictions

I also think so even if I did not use the UI in question.

---

By the way, in my case I have edited my spec to remove the - (id did not really need it).