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
