Check if the outputDir exists before attempting to create the version…

[tyler-mairose-sp]

…s.json file

Description

When generating API specifications using the versioning configuration, there is not check if the directory exists like in the generateApiDocs function. This results in an error when creating the versions.json file.

Motivation and Context

This change is required so that you can generate versioned docs without any issues.

How Has This Been Tested?

I changed my version of the plugin locally and verified that this does in fact fix the issue. I generated versioned api docs and did not get the error after implementing this change.

Screenshots (if appropriate)

Types of changes

• Bug fix (non-breaking change which fixes an issue)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[github-actions]

Visit the preview URL for this PR (updated for commit 369a32a):

https://docusaurus-openapi-36b86--pr892-c4ls8uvo.web.app

_{(expires Thu, 22 Aug 2024 13:20:35 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

[tyler-mairose-sp]

@sserrata Thank you for getting this merged in. We are currently using v3.0.1 of the plugin when would this be slated to release? If possible can we include this PR as well? #893

[sserrata]

Hi @tyler-mairose-sp, install the latest canary release if you need it sooner.

As for #893 I think the implementation works but I have concerns that it may be too open, i.e. it would effectively execute/eval whatever function is provided by the user...but not yet decided on what the actual risk is.

Have you considered alternative approaches, perhaps a custom vendor extension that we could use to inject the classname?

[tyler-mairose-sp]

Hi @tyler-mairose-sp, install the latest canary release if you need it sooner.

As for #893 I think the implementation works but I have concerns that it may be too open, i.e. it would effectively execute/eval whatever function is provided by the user...but not yet decided on what the actual risk is.

Have you considered alternative approaches, perhaps a custom vendor extension that we could use to inject the classname?

Hey @sserrata,

TLDR: I haven't thought of a better way yet.

I originally wrote it so that x-experimental set to true would trigger the class add and that would work. For our use-case we already have a header that designates whether something is experimental so I was trying to avoid adding another custom field to our specs.

I did try to make it open so that more code changes would not be required in the future. A user of this plugin could specify the custom class as the key and their function check as the value in the plugin configuration.

My thought was that whomever uses the plugin would be the one putting in their function check so it would be okay, but I am not sure what all could be run from that function's context.

[sserrata]

I originally wrote it so that x-experimental set to true would trigger the class add and that would work.

One other idea that may work today: have you tried implementing a custom mustache template for this? The idea would be to create if statements that apply a specific sidebar_class_name depending if an operation has an extension. It's not a perfect solution, because there's no way to actually check the value of the extension, only the existence of any extensions...so if you already have custom extensions defined for some of your operations this may not work....

---
id: {{{id}}}
title: "{{{title}}}"
description: "{{{frontMatter.description}}}"
{{^api}}
sidebar_label: Introduction
{{/api}}
{{#api}}
sidebar_label: "{{{title}}}"
{{/api}}
{{^api}}
sidebar_position: 0
{{/api}}
hide_title: true
{{#api}}
hide_table_of_contents: true
{{/api}}
{{#json}}
api: {{{json}}}
{{/json}}
{{#api.method}}
{{#api.extensions.length}}
sidebar_class_name: "experimental api-method"
{{/api.extensions.length}}
{{^api.extensions.length}}
sidebar_class_name: "{{{api.method}}} api-method"
{{/api.extensions.length}}
{{/api.method}}
{{#infoPath}}
info_path: {{{infoPath}}}
{{/infoPath}}
custom_edit_url: null
{{#frontMatter.proxy}}
proxy: {{{frontMatter.proxy}}}
{{/frontMatter.proxy}}
{{#frontMatter.hide_send_button}}
hide_send_button: true
{{/frontMatter.hide_send_button}}
{{#frontMatter.show_extensions}}
show_extensions: true
{{/frontMatter.show_extensions}}
---

{{{markdown}}}

[sserrata]

And here's a snippet of my plugin config showing how to define the template:

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

[sserrata]

Sorry, forgot to add this...technically, there is a way to write an if statement that checks the value of the extension, but it would require writing some preprocessing logic that is currently not open/exposed via the plugin options.

That said, maybe providing a way to pass custom template functions is another viable path to supporting this.

[tyler-mairose-sp]

The idea would be to create if statements that apply a specific sidebar_class_name depending if an operation has an extension.

I did try this, when I got it to add the class name I wanted alongside the api-method and method type (get, patch, post, etc...). I never had luck with it actually applying the class to the sidebar item. It seemed like the sidebar_class_name was not applied. This is why I didn't go this route. I also wasn't able to check a specific header value which brought me back to having to have two fields to manage back in our specs. The custom header and the custom extension x-experimental.

Sorry, forgot to add this...technically, there is a way to write an if statement that checks the value of the extension, but it would require writing some preprocessing logic that is currently not open/exposed via the plugin options.

I can try this out but I would need an example on how it would work or where it is in the code to test and create a new PR with the necessary changes to the plugin.

I appreciate the consideration, we love this plugin and find great value from it. I am happy to help contribute to make it better for everyone that uses it.