diff --git a/.changeset/red-geese-clean.md b/.changeset/red-geese-clean.md new file mode 100644 index 0000000000..b4fc9c0808 --- /dev/null +++ b/.changeset/red-geese-clean.md @@ -0,0 +1,8 @@ +--- +'@backstage/backend-openapi-utils': patch +--- + +Adds new public utility types for common OpenAPI values, like request and response shapes and parameters available on an endpoint. + +**deprecated** `internal` namespace +The internal namespace will continue to be exported but now uses OpenAPI format for path parameters. You should use the new utility types. diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md index 1efab0e85b..ca3f03fcc1 100644 --- a/packages/backend-openapi-utils/README.md +++ b/packages/backend-openapi-utils/README.md @@ -61,6 +61,12 @@ export function createRouter() { } ``` +## FAQs + +### Why am I getting `unknown` as the type for a response? + +This can happen when you have a `charset` defined in your `response.content` section. Something like `response.content[ 'application/json; charset=utf-8:']` will cause this issue. + ## INTERNAL ### Limitations diff --git a/packages/backend-openapi-utils/api-report.md b/packages/backend-openapi-utils/api-report.md index 08ffa23a30..97ea0224d1 100644 --- a/packages/backend-openapi-utils/api-report.md +++ b/packages/backend-openapi-utils/api-report.md @@ -75,11 +75,18 @@ interface CookieObject extends ParameterObject { } // @public (undocumented) -type CookieSchema< +export type CookieParameters< Doc extends RequiredDoc, Path extends PathTemplate>, + Method extends DocPathTemplateMethod, +> = CookieSchema, Method>; + +// @public (undocumented) +type CookieSchema< + Doc extends RequiredDoc, + Path extends DocPath, Method extends DocPathMethod, -> = ParametersSchema, Method, ImmutableCookieObject>; +> = ParametersSchema; // @public export function createValidatedOpenApiRouter( @@ -99,16 +106,16 @@ type DiscriminateUnion = Extract< // @public (undocumented) type DocOperation< Doc extends RequiredDoc, - Path extends keyof Doc['paths'], + Path extends DocPath, Method extends keyof Doc['paths'][Path], > = Doc['paths'][Path][Method]; // @public (undocumented) type DocParameter< Doc extends RequiredDoc, - Path extends Extract, - Method extends keyof Doc['paths'][Path], - Parameter extends keyof Doc['paths'][Path][Method]['parameters'], + Path extends DocPath, + Method extends DocPathMethod, + Parameter extends keyof DocOperation['parameters'], > = DocOperation< Doc, Path, @@ -142,32 +149,28 @@ type DocParameters< }; // @public -type DocPath< - Doc extends PathDoc, - Path extends PathTemplate>, -> = ValueOf<{ - [Template in Extract< - keyof Doc['paths'], - string - >]: Path extends PathTemplate