4

I would love a way to declare some responses that are the same for every endpoint; for example every endpoint will output a 401 if you don't have a proper token, and then there can be another group of endpoints that will all output 404 if you don't have a valid id of something in the beginning of your path.

So for almost every method I find myself copy-pasting things such as this:

* @OA\Response(response=401, description="If no token..."),
* @OA\Response(response=404, description="If ID of thing invalid..."),

The getting started section says that reusable responses are supported, but covering only the properties (of successful responses).

There are no examples for the kind of thing i'm looking for, and I also can't get myself to guess anything that would compile.

Something like @OA\Response(ref="#/components/schemas/Unauthorized") seems like it should be the way (and the compilation doesn't complain about the presence of the ref attribute), but how do i then declare what the Unauthorized schema looks like? Because declaring a @OA\Response says it only expects the fields: "ref", "response", "description", "headers", "content", "links", "x", none of which can serve as an identifier.

I am using this in conjunction with L5-swagger for Laravel support.

Digital Ninja
  • 3,415
  • 5
  • 26
  • 51

1 Answers1

4

Declare a response outside of an operation:

/**
 * @OA\Response(response="Unauthorized", description="If no token...")
 */

This will add it to the #/components/responses/ using the response= as value as key.

Then you're able to reuse it later inside an operation:

/**
 * @OA\Get(
 *   path="/example",
 *   @OA\Response(response=401, ref="#/components/responses/Unauthorized")
 * )
 */
Bob Fanger
  • 28,949
  • 7
  • 62
  • 78
  • 3
    Shame that the `response=401` still has to explicitly be specified in that second block, I was hoping the response definition would hold that information.. But at least the descriptions don't need to be repeated this way, so it does help – Digital Ninja Aug 16 '21 at 08:02
  • FYI this is [in the documentation here](https://zircote.github.io/swagger-php/guide/cookbook.html#reusing-responses). – Ari Cooper-Davis May 18 '23 at 12:36