Remove path aliases from Redoc Documentation - openapi-generator

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.
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.
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.