Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: broken swagger and duplicate route #2050

Merged
merged 5 commits into from
Jun 27, 2023

Conversation

deborahgu
Copy link
Member

@deborahgu deborahgu commented Jun 22, 2023

This API contains a non-CRUD class with no serializer, which the
swagger conversion can't handle automagically. Additionally, there was
an endpoint that had been imported twice because of a file structure
containing multiple urls.py files.

  • specifies the swagger schema for a non-serializer class
  • removes redunandant route via wrong endpoint

Note that the generated swagger document is somewhat confusing, and does not
correctly group the different APIs. This is unavoidable because of two
separate complicating factors:

  • the openAPI specification, which cannot has certain assumptions about base prefix
  • changes within this cluster of APIs, in which endpoint structure has had three
    distinct layouts, before we reached the current, edx-standard structure.
    (appname/api/v#/endpoint_name, api/v#/endpoint_name, and
    api/appname/v#/endpoint_name)

There are ways to address this, but they are all messy (e.g. creating aliases for old endpoints).

Fixes: APER-2531

Run JavaScript tests locally with Karma

There is work being done on a fix to get Karma to run in CI. Until then, however, contributors are required to run these tests locally.

  • Make sure you are inside the devstack container
  • Run make test-karma
  • All tests pass

* specifies the swagger schema for a non-serializer class
* removes redunandant route via wrong endpoint
* adds a comment in a few files so the lower API version number doesn't confuse future maintainers (principle of least surprise)
the actual correct fix for the nested namespaces bug
This API contains a non-CRUD class with no serializer, which the
swagger conversion can't handle automagically. Additionally, there was
an endpoint that had been imported twice because of a file structure
containing multiple urls.py files.

* specifies the swagger schema for a non-serializer class
* removes redunandant route via wrong endpoint

Note that the generated swagger document is somewhat confusing, and does not
correctly group the different APIs. This is unavoidable because of two
separate complicating factors:

* the openAPI specification, which cannot has certain assumptions about base prefix
* changes within this cluster of APIs, in which endpoint structure has had three
  distinct layouts, before we reached the current, edx-standard structure.
  (`appname/api/v#/endpoint_name`, `api/v#/endpoint_name`, and
  `api/appname/v#/endpoint_name`)

There are ways to address this, but they are all messy (e.g. creating aliases for old endpoints).

Fixes: APER-2531
@deborahgu deborahgu changed the title APER-2531 swagger and fixed route fix: broken swagger and duplicate route Jun 26, 2023
@@ -25,68 +27,77 @@ class LearnerCertificateStatusView(APIView):
CanGetLearnerStatus,
)

lms_user_id_schema = openapi.Schema(type=openapi.TYPE_STRING, description="lms_user_id as a string")
Copy link
Contributor

@justinhynes justinhynes Jun 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I don't believe this is a string. The lms_user_id is typically stored as an integer/number.

If I try to use this via Swagger without making lms_user_id a String it will throw an error. However, if you try exercising the API through DRF, this is totally valid data:

{
  "lms_user_id": 3,
  "course_runs": [
    "course-v1:edX+magnets101+2T2023"
  ]
}

If you pass it as a String, it does the right thing though. I expect most times we won't be receiving it as a String, and I have a tiny concern about confusing people who may try to interact with the API via Swagger.

Copy link
Contributor

@justinhynes justinhynes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One tiny comment but overall looks good to me! Thanks for fixing this up.

@deborahgu deborahgu self-assigned this Jun 27, 2023
* fixed data type of one field
@deborahgu deborahgu merged commit 5de53e5 into master Jun 27, 2023
7 of 8 checks passed
@deborahgu deborahgu deleted the dkaplan1/APER-2531_make-credentials-swagger branch June 27, 2023 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants