OpenApi3 - For responses, use Reason Phrase as description instead of status code

[marcelo-s]

Is: Responses description is the string value of the status code. Example:

 responses:
    "400":
      description: "400"

Should: Response description should have the description defined by section 10 of RFC 2616. Example:

 responses:
    "400":
      description: "Bad Request"

If not mistaken the line of code is this one: https://github.com/ePages-de/restdocs-api-spec/blob/b4bd4bb89787af215b49a13264fa122df8f547b8/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt#L337

Perhaps also the option to customize this description.

[ozscheyge]

Hey @marcelo-s ,

Thank you for reaching out!

If I understand your request correctly, it's not about putting the HTTP "Reason Phrase" (how https://datatracker.ietf.org/doc/html/rfc2616#section-6.1 calls it) into the description, but to add another parameter somewhere to set this description (OpenAPI 3 spec allows for any free-text description)?

I'd advise to not introduce a new parameter. There is no equivalent Spring Restdocs descriptor, either. We already provide overloaded document functions (e.g. https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-mockmvc/src/main/kotlin/com/epages/restdocs/apispec/MockMvcRestDocumentationWrapper.kt#L52 ) to optionally pass summary and description parameters which we use on the OpenAPI 3 Operation object: https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt#L229

We could also duplicate the description and write it to the response, too (since each Spring Restdocs document call relates to one request-response pair). Current behavior may not be ideal, but is not a bug by OpenAPI 3 spec (any description works). What would be your idea?

[marcelo-s]

@ozscheyge Thanks for your reply :) . My idea was at least to put the official RFC "Reason Phrase" of the status code as a "Response description". And if possible, allow to customize that description instead of the official "Reason Phrase" for that status code.

Please note that the description that you refer to, and link to, is the description of the whole operation which is unrelated to this enhancement. I only refer to the description of the OpenApi Response Object.

It is true, that sadly Spring Rest Docs does not provide any help here, as there is no way to set this value. But on the conversion function that I linked in the first comment, there is the line of code which is just taking the string value of the status code instead of a human readable description.

As an "easy" implementation, I would suggest to have a map of "statusCode" to "human readable description" based on the RFC document. That way, the function would set the description by calling this map with the status code and getting the "human readable description" for that status code.

[ozscheyge]

Okay, so if it's about the Reason Phrase, it should be pretty straight-forward. There's probably a (Spring) library function for this already.

Please note that the description that you refer to, and link to, is the description of the whole operation which is unrelated to this enhancement. I only refer to the description of the OpenApi Response Object.

Yep, exactly. But wouldn't be wrong either, since each document call relates to one request-response pair, thus also one of the documented status and response objects.

[marcelo-s]

Yep, exactly. But wouldn't be wrong either, since each document call relates to one request-response pair, thus also one of the documented status and response objects.

Yes, you're right. Each document call maps to a specific response. That could be another solution as well. But I still prefer to have the mapping of Status code to Reason Phrase, I think that is more standard in terms of status code description. The document description is used more in the context of naming the example responses.