Remove path aliases from Redoc Documentation

Question

When you have path aliases in openapi.yaml with $ref, for example

paths:
  /municipios/{municipio}:
    get:
      operationId: getMunicipality
      summary: Detalhes sobre Município  
      parameters:
        - in: path
          name: municipio
          required: true
          schema:
            type: string
            example: évora
          allowReserved: true
          description: Município
        - $ref: '#/components/parameters/json'
      responses:
        '200':
          description: Detalhes do Município
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/municipio'

  /municipio/{municipio}:
    $ref: '#/paths/~1municipios~1%7Bmunicipio%7D'

/municipio/{municipio} is de facto merely a path alias of /municipios/{municipio}

In the documentation both paths rules and response samples are shown in duplicate.

I would like to remove path aliases from redocly documentation, that is, basically remove these duplicates, since I just use them due to backward compatibility.

Is there a way to do that?

Answer 1

No, there is no way to do what you are asking. How would it look if you could? The documentation would break if multiple URIs were assigned to the same GET path in the display. If your intent is to keep an old URI only for backwards compatibility, then you are facing a poor API design.

Unfortunately, backwards compatibility will always be an issue for a REST service. Any time you change a path, you will likely have to version your entire API. There are a few workarounds for this if you are entirely against versioning your API.

1. Delete the referenced path from your documentation and override the generated api. You can replace the overridden api path with the new path you want to use. Then update your path description to say that the uri also supports the old one.

2. Remove the reference from the old path and mark it as deprecated instead. You can then continue to support the old path until you feel comfortable removing support for it completely. This will still display both paths, but the deprecated one will be displayed with a strike through.

paths:
  /municipios/{municipio}:
    get:
      operationId: getMunicipality
      summary: Detalhes sobre Município
      parameters:
        - in: path
          name: municipio
          required: true
          schema:
            type: string
            example: évora
          allowReserved: true
          description: Município
        - $ref: '#/components/parameters/json'
      responses:
        '200':
          description: Detalhes do Município
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/municipio'

  /municipio/{municipio}:
    get:
      operationId: getMunicipality
      deprecated: true
      summary: "obsoleto:  Detalhes sobre Município"
      description: Este URL está obsoleto. Atualize sua implementação para usar /municipios/{municipio}. O suporte para este URL será removido em 01 de fevereiro de 2023.
      responses:
        '200':
          description: endpoint obsoleto
          content:
            application/json:
              schema:
                type: string
              example: Este URL está obsoleto. Corrija sua documentação para usar /municipios/{municipio}

I highly recommend option 2. It allows you to inform your consumers of your changes and properly prepare for versioning.