What are the variables in api.mustache template?

[sushengloong]

Documentation link

Missing documentation for https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/6c12cd7fcd74e4fe8c8b02137ee1077daad136ac/demo/api.mustache.

Describe the problem

Every time I regenerate API docs, the api: variable keep changing in all the generated mdx files and it's usually a long string of characters. This is very distracting for code reviews and in git history. I can't find documentation on what it actually is. I also can't find documentation for all other variables in that api.mustache template, which makes it very hard for me to customize the template.

Suggested fix

1. Add documentation to explain what the api: variable is and how we can configure the project such that it doesn't have to change every time we regenerate the mdx files.
2. Add documentation to explain what each of the variables in api.mustache template.

[sserrata]

Hi @sushengloong, the vast majority of the variables referenced in the demo mustache template are documented on https://docusaurus.io/. The api variable is specific to the plugin and it represents the OpenAPI snippet for a given operation. It's necessary for rendering the API Explorer in the right panel. The "long string" is basically just a compressed representation of this snippet. You can disable compression using the currently undocumented disableCompression plugin option, if you want to see the value in clear text:

        petstore: {
            specPath: "examples/petstore.yaml",
            outputDir: "docs/petstore",
            sidebarOptions: {
              groupPathsBy: "tag",
              categoryLinkSource: "tag",
            },
            template: "api.mustache", // Customize API MDX with mustache template
            downloadUrl: "/petstore.yaml",
            hideSendButton: false,
            showSchemas: true,
            disableCompression: true, // disabling api compression
          } satisfies OpenApiPlugin.Options,

However, I suspect the reason your docs/diffs change with each generation is due to the presence of date-time properties in your spec. When no example or examples are explicitly defined in the spec, the plugin attempts to generate an example for a given property. In the case of date-time that it uses javascript Date to calculate the current date-time.

[sserrata]

See #819

[sushengloong]

Thanks @sserrata for your help! Though I don't have any date-time (not even a format:) in my openapi spec.

It seems that the plugin uses Node's zlib for the compression (source) -- could it have generated different outputs on different machines and/or different node versions?

[sserrata]

Hi @sushengloong, it's entirely possible. This SO goes into some of the reasons: https://stackoverflow.com/questions/26516369/zlib-gzip-produces-different-results-for-same-input-on-different-oses