@backstage/backend-openapi-utils 0.0.1 → 0.0.2-next.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/backend-openapi-utils
 
+## 0.0.2-next.1
+
+### Patch Changes
+
+- fe16bd39e83: Use permalinks for links including a line number reference
+- 021cfbb5152: Corrected resolution of parameter nested schema to use central schemas.
+
+## 0.0.2-next.0
+
+### Patch Changes
+
+- 27956d78671: Adjusted README accordingly after the generated output now has a `.generated.ts` extension
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -8,18 +8,18 @@ This package is meant to provide a typed Express router for an OpenAPI spec. Bas
 
 ### Configuration
 
-1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.ts`. In the case of projects that require linting + a license header, you will need to do this manually.
+1. Run `yarn --cwd <package-dir> backstage-cli package schema:openapi:generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.generated.ts`. The command will try to execute both a lint and prettier step on the generated file, where applicable.
 
 2. In your plugin's `src/service/createRouter.ts`,
 
 ```ts
-import {ApiRouter} from `@backstage/backend-openapi-utils`;
-import spec from '../schema/openapi'
-...
-
-export function createRouter(){
+import { ApiRouter } from `@backstage/backend-openapi-utils`;
+import spec from '../schema/openapi.generated';
+// ...
+export function createRouter() {
     const router = Router() as ApiRouter<typeof spec>;
-    ...
+    // ...
+    return router;
 }
 ```
 
@@ -42,4 +42,4 @@ Router() as ApiRouter<DeepWriteable<typeof spec>>
 
 ### Runtime validation
 
-Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/util.ts#L58). However, `AJV` currently doesn't have support for OpenAPI 3.1 and `express-openapi-validator` enforces full URL matching for paths, meaning it cannot be mounted at the router level.
+Using a package like [`express-openapi-validator`](https://www.npmjs.com/package/express-openapi-validator), would allow us to remove [validation of request bodies with `AJV`](https://github.com/backstage/backstage/blob/e0506af8fc54074a160fb91c83d6cae8172d3bb3/plugins/catalog-backend/src/service/util.ts#L58). However, `AJV` currently doesn't have support for OpenAPI 3.1 and `express-openapi-validator` enforces full URL matching for paths, meaning it cannot be mounted at the router level.

package/dist/index.d.ts

@@ -287,11 +287,7 @@ type DocParameters<Doc extends RequiredDoc, Path extends Extract<keyof Doc['path
 /**
  * @public
  */
-type ResolveDocParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = Schema extends ImmutableReferenceObject ? 'parameters' extends ComponentTypes<Doc> ? ComponentRef<Doc, 'parameters', Schema> : never : Schema;
-/**
- * @public
- */
-type ParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ResolveDocParameterSchema<Doc, Schema> extends infer R ? R extends ImmutableSchemaObject ? R extends JSONSchema7 ? FromSchema<R> : never : never : never;
+type ParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = SchemaRef<Doc, Schema> extends infer R ? R extends ImmutableSchemaObject ? R extends JSONSchema7 ? FromSchema<R> : never : never : never;
 /**
  * @public
  */
@@ -438,7 +434,6 @@ type index_d_ImmutablePathObject = ImmutablePathObject;
 type index_d_ImmutableSchemaObject = ImmutableSchemaObject;
 type index_d_DocParameter<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path], Parameter extends keyof Doc['paths'][Path][Method]['parameters']> = DocParameter<Doc, Path, Method, Parameter>;
 type index_d_DocParameters<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path]> = DocParameters<Doc, Path, Method>;
-type index_d_ResolveDocParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ResolveDocParameterSchema<Doc, Schema>;
 type index_d_ParameterSchema<Doc extends RequiredDoc, Schema extends ImmutableParameterObject['schema']> = ParameterSchema<Doc, Schema>;
 type index_d_MapToSchema<Doc extends RequiredDoc, T extends Record<string, ImmutableParameterObject>> = MapToSchema<Doc, T>;
 type index_d_ParametersSchema<Doc extends RequiredDoc, Path extends Extract<keyof Doc['paths'], string>, Method extends keyof Doc['paths'][Path], FilterType extends ImmutableParameterObject> = ParametersSchema<Doc, Path, Method, FilterType>;
@@ -504,7 +499,6 @@ declare namespace index_d {
     index_d_ImmutableSchemaObject as ImmutableSchemaObject,
     index_d_DocParameter as DocParameter,
     index_d_DocParameters as DocParameters,
-    index_d_ResolveDocParameterSchema as ResolveDocParameterSchema,
     index_d_ParameterSchema as ParameterSchema,
     index_d_MapToSchema as MapToSchema,
     index_d_ParametersSchema as ParametersSchema,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-openapi-utils",
   "description": "OpenAPI typescript support.",
-  "version": "0.0.1",
+  "version": "0.0.2-next.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.6"
+    "@backstage/cli": "^0.22.7-next.0"
   },
   "files": [
     "dist"