API Platform - how to document authentication routes

问题

I'm using API Platform v2.2.5 in a Symfony 4 Flex application, consisting of a functioning API with JWT Authentication, a number of resources and the default Open API/Swagger documentation page that is accessible via the /api route. Each API resource is included in the documentation automatically via the platform configuration, as per the library docs.

How do you generate documentation for custom operations such as the security component's auth routes? The API Platform Documentation does not seem to include these instructions.

回答1:

I found the answer thanks to this comment in a Github issue. Since I am using YAML for resource configuration I had to translate, the example for the auth/login endpoint;

App\Entity\User:
  collectionOperations:
  auth:
    route_name: auth
    swagger_context:
      parameters:
        -
          name: username
          required: true
          type: string
          description: "User's username or email address"

        -
          name: password
          required: true
          type: string
          description: "User's password"

      responses:
        200:
          description: "Successful login attempt, returning a new token"
          schema:
            type: object
            required:
              - username
              - password
            properties:
              username:
                type: string

              password:
                type: string

      summary: Performs a login attempt, returning a valid token on success
      consumes:
        - "application/json"
        - "application/ld-json"
      produces:
        - "application/ld-json"

回答2:

Update: its openapi_contex instead of swagger_contex for openapi/swagger v3.

来源：https://stackoverflow.com/questions/49967451/api-platform-how-to-document-authentication-routes