Forum Discussion

GeneVincent's avatar
GeneVincent
New Member
2 years ago

Documenting an API with all operations under a single path

I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:

 

/api?action=action1&some-param=1
/api?action=action2&other-aparam=2

 

If I would put all parameters under a single path, that would force all parameters under that path, too and would mix a lot of parameters that are only valid on certain actions.

 

The Swagger editor doesn't let me create multiple entries for the same path, even if the action parameter is required with a different value on each. and doesn't accept /api?action=action1 as a separate path either.

Is the unique path a requirement from Swagger or from the OpenAPI spec ?

Is there a good workaround how to handle this ?

 

Thanks!

Swagger Editor
  • JOHNSMITH167's avatar
    JOHNSMITH167
    Occasional Contributor
    10 months ago

    The OpenAPI Specification (OAS), formerly known as Swagger, does not restrict you to a unique path. You can have multiple paths in your API documentation, each representing a different resource or endpoint. However, it's common to structure paths in a RESTful way, following best practices for API design.

    In your case, if you have a single endpoint /api that handles different actions based on query parameters, you can still document it effectively in OpenAPI. Here's an example:

    openapi: 3.0.0
    info:
      title: Your API
      version: 1.0.0
    paths:
      /api:
        get:
          summary: Execute API actions
          parameters:
            - name: action
              in: query
              description: The action to perform
              required: true
              schema:
                type: string
                enum: [action1, action2]
            - name: some-param
              in: query
              description: Parameter for action1
              schema:
                type: integer
            - name: other-param
              in: query
              description: Parameter for action2
              schema:
                type: integer
          responses:
            200:
              description: Successful response

     

    In this example, the /api endpoint has a GET operation that takes the action query parameter, which is required and should be one of the values in the enum (action1 or action2). Additional parameters like some-param and other-param are specific to their corresponding actions.

    If you want to include documentation for the "flange" API as well, you can add another path for that:
    paths:
      /flange:
        get:
          summary: Get data about flanges
          parameters:
            - name: flange-param
              in: query
              description: Parameter for the flange API
              schema:
                type: string
          responses:
            200:
              description: Successful response for flange API

    Now, you have documented two different paths: /api for general actions and /flange for the flange API.

    Remember to adapt the parameter names, descriptions, and schemas according to your specific API requirements