Docusaurus-OpenAPI: Preventing Loss of Manual Edits

[miroslavliska]

Dear developers,

I’m able to generate my service from a YAML file using the docusaurus-open-api plugin. I can also manually add extra textual info to the MDX file, like an Introduction section with some custom text.

However, when I modify the YAML and regenerate the docs, I lose my manually added Introduction sections in each MDX file. That’s the problem—I don’t want to manually re-add the text every time.

So, is there an existing mechanism for preserving manually added content when regenerating the docs? Or what’s the recommended approach for handling this?

I'm thinking about adding a parameter for each service that allows including an external MDX file with manually edited content. That way, after regenerating the YAML, the manual content would still be included. This seems like a common use case, so I’m wondering if something like this already exists, or if anyone has suggestions.

Thanks for your help!
Miroslav

[sserrata]

Hi @miroslavliska, I can think of two possible approaches:

• Include and maintain your "extra textual info" in the OpenAPI spec itself
• Maintain the "extra textual info" as separate MD/MDX and use $ref pointers to reference them in the OpenAPI spec.

For example, this snippet illustrates referencing the operation description in a separate md file:

  /api/v33.03/audits/trust/download:
    get:
      description:
        $ref: desc/audits/trust_download_get.md

[miroslavliska]

/api/v33.03/audits/trust/download:
get:
description:
$ref: desc/audits/trust_download_get.md

Thank you very much @sserrata
I was little struggling with the path, but it worked once I started from the presence of yml.

But I am also thinking about avoiding use of yml. I see as a potential approach to modify a template of openapi generation, that will generated new tag to the mdx such as , and for each service described by mdx there could be service-description mdx file. May I ask if this could be a reasonable approach?