Hello and thank you for these repositories!
Following the documentation (for openapi-client-axios
) and running:
npx openapicmd read --strip openapi_client_axios --format json openapi.json > openapi-runtime.json
Results in a definition file with stripped responses, due to removeResponses: true
in PRESETS.openapi_client_axios
.
|
const ALL: StripOptions = { |
|
replaceInfo: true, |
|
removeTags: true, |
|
removeDescriptions: true, |
|
removeExamples: true, |
|
removeExtensions: true, |
|
removeReadOnly: true, |
|
removeSchemas: true, |
|
removeSecuritySchemes: true, |
|
removeServers: true, |
|
replaceResponses: true, |
|
removeResponses: true, |
|
} |
|
openapi_client_axios: { |
|
...ALL, |
|
removeServers: false, // openapi-client-axios uses servers |
|
firstServerOnly: true, // openapi-client-axios only uses first server |
|
}, |
Trying to use this definition file in openapi-client-axios
like this:
import definitionJson from "./openapi-runtime.json";
import { OpenAPIClientAxios, OpenAPIV3 } from "openapi-client-axios";
let definition: OpenAPIV3.Document = definitionJson as OpenAPIV3.Document;
const api = new OpenAPIClientAxios({
definition,
});
Results in an error:
error TS2352: Conversion of type '{ openapi: string; info: { title: string; version: string; }; paths: { "/one_url": { post: { operationId: string; }; }; }; components: {}; }' to type 'Document<{}>' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
Types of property 'paths' are incompatible.
Type '{ "/one_url": { post: { operationId: string; }; }; }' is not comparable to type 'PathsObject<{}, {}>'.
Property '"/one_url"' is incompatible with index signature.
Type '{ post: { operationId: string; }; }' is not comparable to type '{ $ref?: string | undefined; summary?: string | undefined; description?: string | undefined; servers?: ServerObject[] | undefined; parameters?: (ReferenceObject | ParameterObject)[] | undefined; } & { ...; }'.
Type '{ post: { operationId: string; }; }' is not comparable to type '{ get?: { tags?: string[] | undefined; summary?: string | undefined; description?: string | undefined; externalDocs?: ExternalDocumentationObject | undefined; ... 7 more ...; servers?: ServerObject[] | undefined; } | undefined; ... 6 more ...; trace?: { ...; } | undefined; }'.
Types of property 'post' are incompatible.
Property 'responses' is missing in type '{ operationId: string; }' but required in type '{ tags?: string[] | undefined; summary?: string | undefined; description?: string | undefined; externalDocs?: ExternalDocumentationObject | undefined; ... 7 more ...; servers?: ServerObject[] | undefined; }'.
6 let definition: OpenAPIV3.Document = definitionJson as OpenAPIV3.Document;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
So essentially: Property 'responses' is missing in type
. This is due to the open-api
package (which is a dependency for openapi-client-axios
) defining it as required since 2 years back.
https://github.com/kogosoftwarellc/open-api/blob/09fed6d77536b3d7d1d38a2630a096041da773ee/packages/openapi-types/index.ts#L356
export type OperationObject<T extends {} = {}> = {
tags?: string[];
summary?: string;
description?: string;
externalDocs?: ExternalDocumentationObject;
operationId?: string;
parameters?: (ReferenceObject | ParameterObject)[];
requestBody?: ReferenceObject | RequestBodyObject;
responses: ResponsesObject;
callbacks?: { [callback: string]: ReferenceObject | CallbackObject };
deprecated?: boolean;
security?: SecurityRequirementObject[];
servers?: ServerObject[];
} & T;
I see the warning: this will break validation
when digging in the code of this repository, but this is very confusing as a first time user of these libraries. I assumed my definition file was somehow bad.
I'm submitting a PR where I add removeResponses: false
to PRESETS.openapi_client_axios
. I understand if you don't agree on that solution; some alternatives could be:
- Update the docs to reflect that the stripping breaks validation in TypeScript (and advise the usage of
ts-ignore
or something else)
- Provide your own overrides / types in
openapi-client-axios
that make responses
optional again
Being a first time user, I might of course be mistaken in my assumptions...