[Question] Documentation API with Swagger

[Garfield-fr]

Hi,

I would like to documented my API with some descriptions and parameters on entities. I read the swagger specification, but it's not same on ApiResource annotation. Do you have an example ?

I don't find this in your documentation.

My annotation on Communication entity:

/**
 * @ApiResource(
 *     collectionOperations={
 *          "get"={
 *              "method"="GET",
 *              "parameters"={
 *                  "institution"={
 *                      "type"="string",
 *                      "required"=true
 *                  },
 *                  "language"={
 *                      "type"="string",
 *                      "required"=true
 *                  }
 *              },
 *              "description"="Communication collection"
 *          }
 *     },
 *     itemOperations={},
 *
 * )
 */

Thank's

Bertrand

[piotrbrzezina]

Hi

To day I need to write documentation form my custom action. After a few minutes it turned out that the default document is created in DocumentationNormalizer class. If you want to write your own documentation for api you should put this description in "swagger_context" param.

Below is an example how I did it.

/**
 * @ORM\Entity
 * @ApiResource(
 *      itemOperations={
 *          "get"={"method"="GET"},
 *          "put"={"method"="PUT"},
 *          "delete"={"method"="DELETE"},
 *          "send_reset_password_token"={
 *              "route_name"="user_send_reset_password_token",
 *               "swagger_context" = {
 *                  "parameters" = {
 *                      {
 *                          "name" = "email",
 *                          "in" = "path",
 *                          "required" = "true",
 *                          "type" = "string"
 *                      }
 *                  },
 *                  "responses" = {
 *                      "201" = {
 *                          "description" = "email with reset token has been sent",
 *                          "schema" =  {
 *                              "type" = "object",
 *                              "required" = {
 *                                  "email",
 *                                  "username"
 *                              },
 *                              "properties" = {
 *                                   "email" = {
 *                                      "type" = "string"
 *                                   },
 *                                   "fullname" = {
 *                                      "type" = "string"
 *                                   },
 *                                   "username" = {
 *                                      "type" = "string"
 *                                   }
 *                              }
 *                          }
 *                      },
 *                      "400" = {
 *                          "description" = "Invalid input"
 *                      },
 *                      "404" = {
 *                          "description" = "resource not found"
 *                      }
 *                  },
 *                  "summary" = "Send email with token to reset password",
 *                  "consumes" = {
 *                      "application/json",
 *                      "text/html",
 *                   },
 *                  "produces" = {
 *                      "application/json"
 *                   }
 *              }
 *          }
 *      },
 *     attributes={
 *          "normalization_context"={"groups"={"user", "user-read"}},
 *          "denormalization_context"={"groups"={"user", "user-write"}}
 *      }
 * )
 */

[Garfield-fr]

Nice. Thank's

[selmarinel]

Awesome! THX!

@piotrbrzezina
Thanks for the example.

But I can't have a "type"="MyCustomObject".

In your answer look at in the tree : swagger_context > responses > 201 > schema > properties > email > type : How can I reference an Custom Object type and not a string type (type=EmailObject for example) ?

[cryptiklemur]

For anyone looking at @piotrbrzezina's comment now, and using v3 (openapi), its openapi_context instead of swagger_context

[cryptiklemur]

Side-note, documentation on this should be provided (and the developer experience improved) for the JWT auth integration