feat!: rename sanitizeSchema to transformSchema and adjust refs in default implementation

Author: Mairu

docs/api.md

@@ -167,8 +167,8 @@ __Options:__
   - Provide any schema that has an `$id` with a ref as key, check `service.docs.refs` for allowed refs
     - This will add the schema and use it for the given ref
 - `docs` - Any service.docs options that will be merged into the resulting object and would overwrite anything that will be generated
-- `sanitizeSchema` - A function that sanitizes the schema from properties that are not allowed in an OpenApi specification.
-   If not provided a default implementation will be used. 
+- `transformSchema` - A function that transforms the schema to a valid OpenApi schema.
+     If not provided a default implementation will be used which removes unsupported properties and adjust references. 
 
 ### Path support to update nested structures
 

docs/examples/authentication_v5.md

@@ -1,7 +1,7 @@
 ### Example with feathers generated authentication on feathersjs v5 (dove) <!-- {docsify-ignore} -->
 
 1. When you have generated the app with authentication you have to add some things to the initial
-   specs when registering feathers swagger.
+   specs when registering feathers-swagger.
 
    ```typescript
    app.configure(

docs/examples/generated_service_v5.md

@@ -2,33 +2,35 @@
 
 1. Go into your `src/services/{$name}` folder, and open the service you want to edit `${name}.[tj]s`
 2. Import the helper function and import the schemas (example for user service):
-```js  {"highlight": "9-12", "lineNumbers": true}
+```js  {"highlight": "11-14", "lineNumbers": true}
   import { createSwaggerServiceOptions } from 'feathers-swagger';
   import {
-      userDataValidator,
-      userQueryValidator,
-      userResolver,
-      userDataResolver,
-      userQueryResolver,
-      userExternalResolver,
-      userDataSchema,
-      userQuerySchema,
-      userSchema,
-      userPatchSchema,
+    userDataValidator,
+    userPatchValidator,
+    userQueryValidator,
+    userResolver,
+    userExternalResolver,
+    userDataResolver,
+    userPatchResolver,
+    userQueryResolver,
+    userSchema,
+    userDataSchema,
+    userPatchSchema,
+    userQuerySchema
   } from './users.schema';
 ```
 adjust the options when the service is generated
 ```js {"highlight": "6-12", "lineNumbers": true}
   app.use('users', new UserService(getOptions(app)), {
       // A list of all methods this service exposes externally
-      methods: ['find', 'get', 'create', 'update', 'patch', 'remove'],
+      methods: userMethods,
       // You can add additional custom events to be sent to clients here
       events: [],
       docs: createSwaggerServiceOptions({
-          schemas: { userDataSchema, userQuerySchema, userSchema, userPatchSchema },
+          schemas: { userSchema, userDataSchema, userPatchSchema, userQuerySchema },
           docs: {
               // any options for service.docs can be added here
-              securities: ['find', 'get', 'update', 'patch', 'remove'],
+              securities: ['find', 'get', 'patch', 'remove'],
           }
       }),
   });

docs/examples/index.md

@@ -2,6 +2,8 @@
 
 In addition to the examples you can access from the navigation, you can check out the [example application](https://github.com/feathersjs-ecosystem/feathers-swagger/tree/{GITHUB_BRANCH}/example) of the git repository.
 
+There is also a [repository with examples of integrations of feathers-swagger](https://github.com/Mairu/feathersjs-swagger-tests). It contains multiple branches for different versions and configurations.  
+
 It contains many configurations and can be start with `npm start` when feathers-swagger have been checked out.
 
 ### List of examples <!-- {docsify-ignore} -->

docs/getting-started.md

@@ -131,19 +131,24 @@ The docs property can be set as [path service options](https://dove.feathersjs.c
 ```typescript
 import type { createSwaggerServiceOptions } from 'feathers-swagger';
 import {
-  messageDataSchema,
-  messageQuerySchema,
+  // ...
   messageSchema,
-} from './message.schema';
+  messageDataSchema,
+  messagePatchSchema,
+  messageQuerySchema
+} from './messages.schema';
 
 // ...
 
 app.use('message', new MessageService(), {
-  methods: ['find', 'get', 'create', 'update', 'patch', 'remove'],
+  methods: messageMethods,
   events: [],
   docs: createSwaggerServiceOptions({
     schemas: { messageDataSchema, messageQuerySchema, messageSchema },
-    docs: { description: 'My custom service description' }
+    docs: { 
+      description: 'My custom service description',
+      securities: ['all'],
+    }
   })
 });
 ```

lib/utils.js

@@ -72,9 +72,8 @@ const allowedDefaultRefs = [
   'queryParameters'
 ];
 
-// Remove non OpenApi properties (properties from https://swagger.io/specification/#schema-object)
-exports.defaultSanitizeSchema = function defaultSanitizeSchema (schema) {
-  return pick(schema, [
+exports.defaultTransformSchema = function defaultTransformSchema (schema) {
+  const allowedProperties = pick(schema, [
     'title',
     'multipleOf',
     'maximum',
@@ -90,6 +89,8 @@ exports.defaultSanitizeSchema = function defaultSanitizeSchema (schema) {
     'maxProperties',
     'minProperties',
     'required',
+    'dependentRequired',
+    'const',
     'enum',
     'type',
     'allOf',
@@ -109,8 +110,38 @@ exports.defaultSanitizeSchema = function defaultSanitizeSchema (schema) {
     'xml',
     'externalDocs',
     'example',
-    'deprecated'
+    'deprecated',
+    '$ref',
+    '$dynamicRef',
+    '$anchor',
+    '$dynamicAnchor',
+    '$recursiveRef',
+    '$recursiveAnchor',
+    '$defs',
+    '$comment'
   ]);
+
+  if (allowedProperties.$ref && !allowedProperties.$ref.includes('#')) {
+    allowedProperties.$ref = '#/components/schemas/' + allowedProperties.$ref;
+  }
+
+  if (allowedProperties.items) {
+    allowedProperties.items = defaultTransformSchema(allowedProperties.items);
+  }
+
+  if (allowedProperties.properties) {
+    allowedProperties.properties = Object.entries(allowedProperties.properties).reduce(
+      (previousValue, [key, value]) => {
+        return {
+          ...previousValue,
+          [key]: defaultTransformSchema(value)
+        };
+      },
+      {}
+    );
+  }
+
+  return allowedProperties;
 };
 
 function determineSchemaPrefix (schemas) {
@@ -134,9 +165,9 @@ function determineSchemaPrefix (schemas) {
   return undefined;
 }
 
-exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ schemas, docs, sanitizeSchema }) {
+exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ schemas, docs, transformSchema }) {
   const serviceDocs = { schemas: {}, refs: {} };
-  const sanitizeSchemaFn = sanitizeSchema || exports.defaultSanitizeSchema;
+  const transformSchemaFn = transformSchema || exports.defaultTransformSchema;
 
   let unspecificSchemas;
   const prefix = determineSchemaPrefix(schemas);
@@ -159,7 +190,7 @@ exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ sc
       const listSchemaName = `${baseSchemeName}List`;
 
       serviceDocs.schemas = {
-        [baseSchemeName]: sanitizeSchemaFn(resultSchema),
+        [baseSchemeName]: transformSchemaFn(resultSchema),
         [listSchemaName]: {
           type: 'array',
           items: { $ref: `#/components/schemas/${baseSchemeName}` }
@@ -170,7 +201,7 @@ exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ sc
 
       if (dataSchema) {
         const dataSchemeName = dataSchema.$id || `${baseSchemeName}Data`;
-        serviceDocs.schemas[dataSchemeName] = sanitizeSchemaFn(dataSchema);
+        serviceDocs.schemas[dataSchemeName] = transformSchemaFn(dataSchema);
         serviceDocs.refs.createRequest = dataSchemeName;
         serviceDocs.refs.updateRequest = dataSchemeName;
       }
@@ -181,13 +212,13 @@ exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ sc
           properties: omit(baseQuerySchema.properties, ['$limit', '$skip'])
         };
         const querySchemaName = querySchema.$id || `${baseSchemeName}Query`;
-        serviceDocs.schemas[querySchemaName] = sanitizeSchemaFn(querySchema);
+        serviceDocs.schemas[querySchemaName] = transformSchemaFn(querySchema);
         serviceDocs.refs.queryParameters = querySchemaName;
       }
 
       if (patchSchema) {
         const patchSchemaName = patchSchema.$id || `${baseSchemeName}PatchData`;
-        serviceDocs.schemas[patchSchemaName] = sanitizeSchemaFn(patchSchema);
+        serviceDocs.schemas[patchSchemaName] = transformSchemaFn(patchSchema);
         serviceDocs.refs.patchRequest = patchSchemaName;
       }
 
@@ -203,7 +234,7 @@ exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ sc
   Object.entries(unspecificSchemas).forEach(([key, schema]) => {
     const schemaName = schema.$id;
     if (schemaName) {
-      serviceDocs.schemas[schemaName] = sanitizeSchemaFn(schema);
+      serviceDocs.schemas[schemaName] = transformSchemaFn(schema);
       if (allowedDefaultRefs.includes(key)) {
         serviceDocs.refs[key] = schemaName;
       }