dtsgenerator
dtsgenerator copied to clipboard
Include path parameters and path as string type in the Paths section
The Paths
section of the output file is structured like:
- Paths
- PathId
- Parameters
- Responses
- PathId
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
- PathId
Where PathParameters
is the same structure as Parameters
and Endpoint
is a string literal.
@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
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"
.
@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
)
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.