Preserve descriptions of $ref types

[jankuca]

Currently, when there is an aliased type used, the JSDoc description is lost in favor of the description of the aliased type.

/** A */ // This is preserved.
type AliasedType = string

@body _body: {
  /** B */ // This is lost.
  'x': AliasedType
}

The AliasedType is turned into a components/schema item with the description preserved whereas the body property "x" loses the description. This is due to the OpenAPI format limitation which does not allow descriptions for $ref schemas.

I think it would be a nice fix (optional possibly) to inline the aliased types when used together with a JSDoc description.

The code above would effectively be the same as

@body _body: {
  /** B */ // This is now preserved.
  'x': string
}

The only way to preserve the descriptions is currently inlining the types manually and having a lot of duplication within the API Spot definition.

[jankuca]

I have implemented this logic in PR #1168.

[lfportal]

Hi @jankuca, sorry for the delay, I've been away the past week 🙏. As you've suggested this is a limitation of the OpenAPI 3.0 specification. Whilst your solution solves for your use case, conditional inlining based on presence of a comment is quite tailored and implicit - the generated OpenAPI document would deviate structurally from the SPOT contract.

I did a little bit of digging into this issue from the OpenAPI perspective and it appears it has been an active topic in the community - and has been addressed in the upcoming OpenAPI 3.1 specification (see OpenAPI 3.1 RC1 | Reference Object - reference objects will allow description and summary as sibling elements. My preference here would be to introduce the 3.1 version of the generator for SPOT rather than working around the limitation for the 3.0 generator. Would that work for you @jankuca?

[jankuca]

@lfportal Yeah, that makes total sense and it by far the cleanest way to go. I didn't know about the proposal and I love seeing this.

We are using redoc for generating documentation for our API. I am not sure about the support for the proposal there as of right now but I expect the project to adhere to future versions of OpenAPI eventually. I can continue using my workaround until then.