diff --git a/docs/custom-methods.md b/docs/custom-methods.md index 32959d4..41b0977 100644 --- a/docs/custom-methods.md +++ b/docs/custom-methods.md @@ -103,6 +103,46 @@ app.use('some', new SomeService(options), { + +### **How to document custom methods** + +`feathers-swagger` allows you to pass a `Request` and `Response` schema to document what your custom method expects and returns. + +```typescript +export const userApproveRequest = Type.Object( + { + userMessage: Type.String({ + description: 'A message by the user' + }) + }, + { + $id: 'userApproveRequest', + additionalProperties: false + } +) + +export const userApproveResponse = Type.Object( + { + successMessage: Type.String() + }, + { + $id: 'userApproveResponse', + additionalProperties: false + } +) +``` + +In `createSwaggerServiceOptions` you can pass these new schemas + +```typescript + docs: createSwaggerServiceOptions({ + schemas: {..., userApproveRequest, userApproveResponse}, + ... + }) +``` + + + ## Example Check out the [example](/examples/custom_methods.md) to see it in action. diff --git a/lib/utils.js b/lib/utils.js index a8625cb..0184235 100644 --- a/lib/utils.js +++ b/lib/utils.js @@ -50,28 +50,6 @@ exports.idPathParameters = function idPathParameters (idName, idSeparator) { return `{${Array.isArray(idName) ? idName.join(`}${idSeparator}{`) : idName}}`; }; -const allowedDefaultRefs = [ - 'findResponse', - 'getResponse', - 'createRequest', - 'createResponse', - 'createMultiRequest', - 'createMultiResponse', - 'updateRequest', - 'updateResponse', - 'updateMultiRequest', - 'updateMultiResponse', - 'patchRequest', - 'patchResponse', - 'patchMultiRequest', - 'patchMultiResponse', - 'removeResponse', - 'removeMultiResponse', - 'filterParameter', - 'sortParameter', - 'queryParameters' -]; - exports.defaultTransformSchema = function defaultTransformSchema (schema) { const allowedProperties = pick(schema, [ 'title', @@ -235,9 +213,7 @@ exports.createSwaggerServiceOptions = function createSwaggerServiceOptions ({ sc const schemaName = schema.$id; if (schemaName) { serviceDocs.schemas[schemaName] = transformSchemaFn(schema); - if (allowedDefaultRefs.includes(key)) { - serviceDocs.refs[key] = schemaName; - } + serviceDocs.refs[key] = schemaName; } });