Ensure OpenAPI specification is generated correctly

added issuetypeTask teamIdentity workflowNeeds Refinement labels

marked this issue as blocking #22 (closed)

@mk2155 to split this down to "fixes" to spectacular generation for activate account and process to automate generation and release of the specification.

changed the description

marked this issue as blocking #24 (closed)

changed the description

added time estimate of 1d

added workflowSprint Ready label and removed workflowNeeds Refinement label

mentioned in epic uis/devops&205

changed iteration to IAM Sprint Nov 20, 2024 - Dec 3, 2024

added workflowIn Progress label and removed workflowSprint Ready label

assigned to @ee345

created branch 21-ensure-openapi-specification-is-generated-correctly to address this issue

mentioned in merge request !52 (merged)

Not sure why Currently the OpenAPI specification generated by the spectacular management command is not correct, as I have the generated file: Activate_Account__v1alpha1___3_.yaml

Yup. It looks to me that it has the endpoints in. I suppose this task turns into just:

Add unit test to verify OpenAPI generation produces valid output and includes expected endpoints

Using something like https://pypi.org/project/openapi-spec-validator/.

It looks to me that it has the endpoints in.

However, looking carefully I see that the responses are wrong. For example:

paths:
  /token/:
    post:
      operationId: token_create
      tags:
      - token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRequest'
          description: ''

The 200 response schema should be something different to the request schema since the response will have expires_in and access_token fields, etc.

It appears from the DRF Spectacular docs that one needs to specify the response schema somehow. The current post method doesn't use any serializer at all to form responses:

    def post(self, request, *args, **kwargs):
        # ...

        return Response(
            data={
                "expires_in": int(self.get_token_ttl().total_seconds()),
                "access_token": token,
                "token_type": "bearer",
            },
            headers={
                "Cache-Control": "no-store",
                "Pragma": "no-cache",
            },
        )

So it looks like you'd need to add something like a TokenResponseSerializer and use @extend_schema.

The OpenAPI spec also doesn't include any of the non-200 error responses.

E.g https://developer.api.apps.cam.ac.uk/docs/oauth2/1/routes/token/post includes 400 and 403 responses in the schema. And I think we can also generate 401s too?

E.g https://developer.api.apps.cam.ac.uk/docs/oauth2/1/routes/token/post includes 400 and 403 responses in the schema. And I think we can also generate 401s too?

Nope. Only 400s.