Include path parameters and path as string type in the Paths section

[iansan5653]

The Paths section of the output file is structured like:

• Paths
  • PathId
    • Parameters
    • Responses

However, Parameters there only includes query parameters (ie, endpoint?PARAMETER_NAME), not path parameters (ie endpoint/{PARAMETER_NAME}). Also there's no information about the endpoint itself.

I propose adding to the existing structure:

• Paths
  • PathId
    • Parameters
    • Responses
    • PathParameters
    • Endpoint

Where PathParameters is the same structure as Parameters and Endpoint is a string literal.

[horiuchi]

@iansan5653 The PathParameters and Endpoint properties do not seem to be present in the OpenAPI v3 specification. What specification are you talking about?

OpenAPI v3 Spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operationObject

[iansan5653]

I don't use OpenAPI at the moment so I'm speaking from memory, but here's an example from an old project of an endpoint with a path parameter:

{
"/events/{eventId}/attendees": {
  "get": {
    "summary": "...",
    "tags": ["events"],
    "operationId": "getAttendees",
    "parameters": [
      {
        "name": "eventId",
        "in": "path",
        "description": "...",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "List of attendees",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#..."
            }
          }
        }
      }
    }
  }
}
}

In this case, there's a string path parameter called eventId.

I think with the Endpoint attribute I was just suggesting to add the endpoint path as a string literal to the generated types - ie, in this case it would be "/events/{eventId}/attendees".

[npdev453]

@iansan5653, looks like PathParameters currently generating and expected as well.

Endpoint I can't imagine any cases where it could be useful, and why .d.ts should provide it. Can you provide any use cases or code examples? (possible name PathTempalte, and possible should also generate a wiring map $PathTemplate->namespace)

Path Templating Spec

[iansan5653]

When you build a TypeScript service that uses the types, you will eventually need to use the path to query the endpoints. Without the path at a string literal in the types, there's no way to ensure it's correct.

For example:

// dtsgenerator output
declare namespace FindPetById {
    namespace Parameters {
        export type Id = number; // int64
    }
    export interface PathParameters {
        id: Parameters.Id /* int64 */;
    }
    namespace Responses {
        export type $200 = Pet;
        export type Default = Error;
    }
}

// example service function
async function findPetById(params: FindPetById.PathParameters): Promise<FindPetById.Responses.$200> {
  const url = serverBase + "/findPet/" + params.id // This is wrong, but doesn't cause a type error because we can't say "const url: FindPetById.Endpoint"
  return await fetch(url, ...)
}

I'm actually not sure of the best way to do it with path parameters. Maybe just provide the raw string type (ie "a/{param}/b") or maybe there's a way to take advantage of TypeScript's new template string types.