Feature Request: Add Auto-generated Comments to Top of Generated Files

[amikofalvy]

What problem will this feature address?

This feature will clearly indicate which files are auto-generated, preventing contributors from unintentionally editing generated files directly, which can lead to overwritten changes or merge conflicts.

Describe the solution you'd like

Introduce a new optional parameter to the OpenAPI.generateFiles function, e.g., addGeneratedComment, accepting:

• true (default): Inserts a standardized comment.
• false: No comment is added.
• string: Inserts a custom provided comment.

Example usage with current generate-docs.mjs script:

await OpenAPI.generateFiles({
  schemaPath: './openapi.json',
  output: './docs/openapi',
  addGeneratedComment: true, // or provide a custom string
});

Default standardized comment:

// Comment format for MDX files
{/*
  This file was auto-generated by Fuma Docs.
  Do not edit this file directly. Any changes should be made by running the generation command again.
*/}

Describe alternatives you've considered

• Initially, I considered not making this feature configurable, but I realized it might disrupt workflows of existing users who prefer not to have additional comments in their generated files.
• Secondly, I considered making the configuration a simple boolean. However, providing a string option for custom messages makes the feature more versatile. Users can include specific instructions or commands (e.g., pnpm build or pnpm run generate) tailored to their project needs.
• Lastly, I thought about the complexity of overloading the configuration type. Ultimately, I found that a clear and simple true | false | string option strikes a good balance, catering both to straightforward use cases and more advanced configurations without added complexity.

Additional context

Examples from similar tools:

• GraphQL Code Generator:

  // THIS IS A GENERATED FILE, DO NOT EDIT!

• Prisma Client:

  // This file was automatically generated by Prisma.
  // Do not edit this file directly.

• Next.js:

  // Automatically generated by Next.js. Do not modify.

• OpenAPI Generator:

  // Code generated by OpenAPI Generator. DO NOT EDIT.

I'm happy to contribute this feature myself if the maintainers approve. Thanks for creating and maintaining such a useful tool!

[fuma-nama]

Sounds good! I didn't consider that because it was supposedly a process happen at production build, welcome for PR ;)

Note that MDX uses a different syntax for comments:

{/* Comment */}

[amikofalvy]

I propose a solution in #1512