TLDR: We don’t have a way to add several descriptions to OpenAPI objects, in different languages. We won’t have it soon.
In other words, if you want to write something like this:
description:
en: Update an existing entity
es: Actualizar una entidad existente
zn: 更新现有实体
That’s not possible. This is quite sad.
What OpenAPI offers instead
Adding language codes to the OpenAPI specification is a huge headache for people working on it. It will never look like the example above even though it looks natural and simple. See this or this discussion on Github.
Instead of solving this little practical problem directly, OpenAPI developers propose to use overlays. Overlays are complex, but powerful. They’re in review since 2018.
The proposal introduces a new type of objects, called Update object. The idea is to create a new file, for example, overlay-es.yml and put something like this to it:
overlay: 1.0.0
info:
title: Spanish overlay
version: 1.0.0
updates:
- target: "@"
value:
info:
x-overlay-applied: spanish-overlay
paths:
"/entity":
put:
description: "Actualizar una entidad existente"
Users will see descriptions in Spanish with Spanish overlay enabled.
Working group is created, but the status is not clear.