CODEWITHSUNDEEP
openapiswagger-editor
Petro Gromovo
Petro Gromovo

Reputation: 2171

How to define a path with two optional parameters in OpenAPI 3.0?

I registered at SwaggerHub and created a new API using OpenAPI 3.0. In my API, the /tasks path has 2 non-required parameters, but I can not set them as not required - the editor shows the "Not allowed Values" error.

Here's my API definition:

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number to be fetched. If missed default 1.
          required: true
          schema:
            type: integer
        - name: order_by
          in: path
          description: The order_by  be fetched. 
          required: false  // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
        - name: filter
          in: path
          description: The filter for title field. 
          required: false // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid tasks supplied
        '404':
          description: tasks were not found

But if I remove the required attributes, I get 2 errors:

should have required property 'required'
missingProperty: required

What is the valid syntax?

Upvotes: 8

Views: 10351

Answers (1)

Helen
Helen

Reputation: 97609

Are these parameters supposed to be path parameters or query parameters?

Path parameters (in: path) are part of the endpoint path, and as such must be indicated by {...} in the path template:

paths:
  /tasks/{page}/{order_by}/{filter}:

Path parameters are always required, i.e. they must have required: true.

Query parameters are send in the query string, e.g. /tasks?page=...&order_by=.... To use query parameters, change the parameter location to in: query.

More information: Describing Parameters

Upvotes: 7

Related Questions