[Feature Request] Support omitting fields rather than entire models

[nreprogle-restorehope]

Hi there! First of all, thank you for this generator. This is super helpful for my org, as hand-typing OpenAPI schema for the hundreds of models and thousands of fields we have would be impossible.

That being said, we have models that we would like to omit certain fields on, but not the entire model. For example, let's say we have an Account model may have hashed passwords in it. We want users of our API to be able to access this model (Say, for updating things like name, description, or other fields one may update on an Account), but we don't want them to access or even know about the password field (Or any sensitive fields). However, this field is automatically added to the OpenAPI schema when generated.

Since this library already generates descriptions for model properties based on the field.documentation property, would it be possible to have a field be omitted if a specific phrase or comment existed in the documentation for it? For example, maybe if the comment contains @openapi-omit the model would not be added to the generation chain? Here's an example snippet of an updated generatePropertiesFromModel function that would support this (Not tested, only theoretical):

export function generatePropertiesFromModel(
    model: GeneratorOptions['dmmf']['datamodel']['models'][0],
    allModels: GeneratorOptions['dmmf']['datamodel']['models'],
    enums: GeneratorOptions['dmmf']['datamodel']['enums'],
): Record<string, SchemaObject | ReferenceObject> {
    const properties: Record<string, SchemaObject | ReferenceObject> = {};
    for (const field of model.fields) {

        // Updated function, omits a field if the documentation string contains a specified value. Could also be rewritten to be "startsWith" or something
        if(field.documentation?.includes("@openapi-omit")) continue;

        // Existing code, truncated for brevity
        let property: SchemaObject | ReferenceObject;
        // ...
        properties[field.name] = property;
    }

    return properties;
}

This would be hugely beneficial for teams needing models to be generated but certain fields hidden within those models, without needing to manually edit the model afterwards. Thank you again for your work on this!!

[nitzano]

Thanks so much for the detailed suggestion and example code @nreprogle-restorehope ! This is a great idea and would definitely be useful. I'm working on implementing this feature now. Appreciate your contribution! 🙏

[nreprogle-restorehope]

Thank you so much!

---

As a workaround (and for those that may find this issue in the future before the suggested feature is implemented), we created a @redocly/cli plugin that does this when bundling. The code is here:

/**
 * Remove object properties by:
 *  - exact property name match (removeNames)
 *  - description contains marker (marker)
 *
 * Config:
 *  - removeNames: string[] (default [])
 *  - marker: string | null (default null)
 *  - ignoreCase: boolean (default true)
 */
function omitProps({
	removeNames = [],
	marker = null,
	ignoreCase = true,
  } = {}) {
	const names = Array.isArray(removeNames) ? removeNames : [removeNames];
	const normalizedNames = new Set(
	  names
		.filter((x) => typeof x === "string" && x.length > 0)
		.map((x) => (ignoreCase ? x.toLowerCase() : x))
	);
  
	const needle = typeof marker === "string" && marker.length > 0 ? marker : null;
  
	const nameMatches = (propName) => {
	  if (typeof propName !== "string") return false;
	  const key = ignoreCase ? propName.toLowerCase() : propName;
	  return normalizedNames.has(key);
	};
  
	const descMatches = (desc) => {
	  if (!needle) return false;
	  if (typeof desc !== "string") return false;
	  return ignoreCase
		? desc.toLowerCase().includes(needle.toLowerCase())
		: desc.includes(needle);
	};
  
	return {
	  Schema: {
		// Use enter() so removed properties aren't traversed (helps avoid $ref resolution issues).
		enter(schema) {
		  if (!schema || typeof schema !== "object") return;
		  if (!schema.properties || typeof schema.properties !== "object") return;
  
		  const original = schema.properties;
		  const next = {};
		  const removed = new Set();
  
		  for (const [propName, propSchema] of Object.entries(original)) {
			const shouldRemove =
			  nameMatches(propName) || descMatches(propSchema?.description);
  
			if (shouldRemove) {
			  removed.add(propName);
			  continue;
			}
			next[propName] = propSchema;
		  }
  
		  if (removed.size === 0) return;
  
		  // Assign rebuilt properties object (more reliable than delete in-place).
		  schema.properties = next;
  
		  // Keep required in sync.
		  if (Array.isArray(schema.required)) {
			const req = schema.required.filter((n) => !removed.has(n));
			if (req.length > 0) schema.required = req;
			else delete schema.required;
		  }
  
		  // Optional cleanup: if no properties remain, remove properties entirely.
		  if (Object.keys(schema.properties).length === 0) {
			delete schema.properties;
		  }
  
		  process.stderr.write(
			`[omit-props] removed: ${[...removed].join(", ")}\n`
		  );
		},
	  },
	};
  }

export default function omitPropsPlugin() {
	return {
		id: "omit-props",
		decorators: {
			oas3: {
				"omit-props-by-description": omitProps,
			},
		},
	};
}

And to configure it, add the following to your redocly.yaml file (Or created it if you haven't):

plugins:
    - openapi/scripts/omit-props-by-desc.mjs

decorators:
    omit-props/omit-props-by-description:
        marker: "[internal]"
        removeNames:
            - password
            - email
            - [Any other field you want to have globally removed, even without the marker being in the generated]
        ignoreCase: true

extends:
    - recommended

To use it, just add "[internal]" anywhere in the Prisma comment of a field you want omitted, and when prisma-openapi generates the file, it'll include that in the field's description. Then, you can use npx @redocly/cli bundle [spec file] to bundle it, running the plugin in the process and removing fields with either "[internal]" in the description or if the field matches the name of one of the removeNames fields.

[nitzano]

@nreprogle-restorehope Added this new feature in v1.6.0 🚀

You can now exclude fields in two ways:

1. @openapi.ignore comment in the field (your suggestion)
2. Adding them to excludeFields in the generator in prisma file

https://github.com/nitzano/prisma-openapi?tab=readme-ov-file#field-exclusion

Please let me know if it works for you :)

[nreprogle-restorehope]

I'll give it a test in just a bit and let you know. Thanks again!!

[nreprogle-restorehope]

Working well for us, thanks again so much for your work on this project!