Allow custom server/base urls in config

[Dr-Electron]

Is your feature request related to a problem?

Currently I generate a lot of API docs with your plugin, but as the endpoints are not fixed for our staging and production environment, I can't have static urls inside the specs.

Describe the solution you'd like

Would be nice to be able to specify a list of urls in the config.

Describe alternatives you've considered

I saw that there was another issue open at some point, which would allow adding new urls on the website, but that's not what I would need. It would be a nice feature, but for us the problem is more that we can't specify static urls. But I guess both could be added in one PR, with a config that allows the user to disable/enable the "add custom url in browser" feature and a possible list of urls.

[sserrata]

Hi @Dr-Electron, although what you're asking for is technically feasible, it would effectively allow the plugin to override the OpenAPI specification, which is a departure from the "read-only" approach we take today. Were you able to come up with a suitable workaround?

[Dr-Electron]

Hi @Dr-Electron, although what you're asking for is technically feasible, it would effectively allow the plugin to override the OpenAPI specification, which is a departure from the "read-only" approach we take today. Were you able to come up with a suitable workaround?

Hi @sserrata I See your point, but I think having the possibility to allow custom "configs" on top of the spec is really worth it. Sometimes you are just not able to change the spec. In our case:

1. the specs are distributed between multiple repos so if we change public infrastructure, we need to adapt all specs
2. some specs are part of a formal process, so changing them takes time
3. People mightt run their own endpoint, so if adding of custom urls on runtime would be allowed they could also test the specs with their own servers, which I think is a nice addition.

Other than that I didn't think too much about it yet, wanted to hear some other opinions first.

[lucas-tortora]

I think it'd be a handy feature for anyone using an API for which they don't control the spec.

As well, it'd be nice to allow users to manually input an endpoint when they hit edit. It'd be a simple way for them to test if they deployed their API properly, or have ready-to-go API calls they can copy.

[qido2]

This can already be achieved by adjusting the OpenAPI spec in Swagger file:

• for swagger.yml

  servers:
    # Create a template URL and put the variables into {curly brackets}
    - url: https://{host}:{port}/v1
      # Define the variables and their default values
      variables:
        host:
          default: localhost
        port:
          default: '3000'
  

• for swagger.json

  "servers": [
    {
      "url": "https://{host}:{port}/v1",
      "variables":
      {
        "host":
        {
          "default": "localhost"
        }
        "port":
        {
          "default": "3000"
        }
      }
    }
  ],
  

You can inject this before or after you generate the Swagger file.

Inject before

For example in C# when using the Swashbuckle.AspNetCore you can do this by defining an OpenApiServer:

// Define new OpenApiServer
options.AddServer(new OpenApiServer
{
    // Create a template URL and put the variables into {curly brackets}
    Url = "https://{host}:{port}/v1",
    // Define the variables and their default values
    Variables =
    {
        { "host": new OpenApiServerVariable { Default = "localhost" }},
        { "port": new OpenApiServerVariable { Default = 3000 }}
    }
});

Inject after

To inject after you'll need to augment the generated Swagger file.

I created a separate .js script which runs before executing the gen-api-docs command and generates the docusaurus-plugin-openapi-docs config as a separate .json file. The config file is then just referenced inside the plugin configuration section of the docusaurus.config.js file.

How the script works:

1. Load Swagger files from URLs defined as a list in a separate .json file.
2. Replace (or add if missing) the default servers value with the desired template.
3. Add link to the docusaurus-plugin-openapi-docs config file.

You can learn more about the posibilities in the Swagger documentation:

• https://swagger.io/docs/specification/api-host-and-base-path/

[sserrata]

Supporting helpers to adapt OpenAPI spec server URLs for different envs is outside of the scope of this plugin. As mentioned in this thread, maintainers can use variables to support custom server URLs as needed.