Update urlconf to add accessible schema/Swagger URLs, add better typing for B2B data, update OpenAPI spec (#2672)

Author: jkachel

main/urls.py

@@ -18,6 +18,7 @@
 from django.conf.urls.static import static
 from django.contrib import admin
 from django.urls import include, path, re_path
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 from mitol.apigateway.views import ApiGatewayLogoutView
 from oauth2_provider.urls import base_urlpatterns, oidc_urlpatterns
 from wagtail import urls as wagtail_urls
@@ -39,6 +40,12 @@
     path("admin/", admin.site.urls),
     path("hijack/", include("hijack.urls")),
     path("robots.txt", include("robots.urls")),
+    re_path(r"^api/schema/$", SpectacularAPIView.as_view(), name="schema"),
+    re_path(
+        r"^api/schema/swagger-ui/$",
+        SpectacularSwaggerView.as_view(url_name="schema"),
+        name="swagger",
+    ),
     path("", include("authentication.urls")),
     path("", include("authentication.new_urls")),
     path("", include("openedx.urls")),

openapi/specs/v0.yaml

@@ -2385,9 +2385,7 @@ components:
         b2b_organizations:
           type: array
           items:
-            type: object
-            additionalProperties: {}
-          description: Get the organizations for the user
+            $ref: '#/components/schemas/UserOrganization'
           readOnly: true
       required:
       - b2b_organizations
@@ -2401,6 +2399,48 @@ components:
       - is_superuser
       - legal_address
       - updated_on
+    UserOrganization:
+      type: object
+      description: |-
+        Serializer for user organization data.
+
+        Slightly different from the OrganizationPageSerializer; we only need
+        the user's orgs and contracts.
+      properties:
+        id:
+          type: integer
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+          description: The name of the organization
+        description:
+          type: string
+          readOnly: true
+          description: Any useful extra information about the organization
+        logo:
+          type: string
+          format: uri
+          readOnly: true
+          description: The organization's logo. Will be displayed in the app in various
+            places.
+        slug:
+          type: string
+          readOnly: true
+          description: The name of the page as it will appear in URLs e.g http://domain.com/blog/[my-slug]/
+          pattern: ^[-\w]+$
+        contracts:
+          type: array
+          items:
+            $ref: '#/components/schemas/ContractPage'
+          readOnly: true
+      required:
+      - contracts
+      - description
+      - id
+      - logo
+      - name
+      - slug
     UserProfile:
       type: object
       description: Serializer for profile

openapi/specs/v1.yaml

@@ -2385,9 +2385,7 @@ components:
         b2b_organizations:
           type: array
           items:
-            type: object
-            additionalProperties: {}
-          description: Get the organizations for the user
+            $ref: '#/components/schemas/UserOrganization'
           readOnly: true
       required:
       - b2b_organizations
@@ -2401,6 +2399,48 @@ components:
       - is_superuser
       - legal_address
       - updated_on
+    UserOrganization:
+      type: object
+      description: |-
+        Serializer for user organization data.
+
+        Slightly different from the OrganizationPageSerializer; we only need
+        the user's orgs and contracts.
+      properties:
+        id:
+          type: integer
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+          description: The name of the organization
+        description:
+          type: string
+          readOnly: true
+          description: Any useful extra information about the organization
+        logo:
+          type: string
+          format: uri
+          readOnly: true
+          description: The organization's logo. Will be displayed in the app in various
+            places.
+        slug:
+          type: string
+          readOnly: true
+          description: The name of the page as it will appear in URLs e.g http://domain.com/blog/[my-slug]/
+          pattern: ^[-\w]+$
+        contracts:
+          type: array
+          items:
+            $ref: '#/components/schemas/ContractPage'
+          readOnly: true
+      required:
+      - contracts
+      - description
+      - id
+      - logo
+      - name
+      - slug
     UserProfile:
       type: object
       description: Serializer for profile

openapi/specs/v2.yaml

@@ -2385,9 +2385,7 @@ components:
         b2b_organizations:
           type: array
           items:
-            type: object
-            additionalProperties: {}
-          description: Get the organizations for the user
+            $ref: '#/components/schemas/UserOrganization'
           readOnly: true
       required:
       - b2b_organizations
@@ -2401,6 +2399,48 @@ components:
       - is_superuser
       - legal_address
       - updated_on
+    UserOrganization:
+      type: object
+      description: |-
+        Serializer for user organization data.
+
+        Slightly different from the OrganizationPageSerializer; we only need
+        the user's orgs and contracts.
+      properties:
+        id:
+          type: integer
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+          description: The name of the organization
+        description:
+          type: string
+          readOnly: true
+          description: Any useful extra information about the organization
+        logo:
+          type: string
+          format: uri
+          readOnly: true
+          description: The organization's logo. Will be displayed in the app in various
+            places.
+        slug:
+          type: string
+          readOnly: true
+          description: The name of the page as it will appear in URLs e.g http://domain.com/blog/[my-slug]/
+          pattern: ^[-\w]+$
+        contracts:
+          type: array
+          items:
+            $ref: '#/components/schemas/ContractPage'
+          readOnly: true
+      required:
+      - contracts
+      - description
+      - id
+      - logo
+      - name
+      - slug
     UserProfile:
       type: object
       description: Serializer for profile

users/serializers.py

@@ -192,6 +192,7 @@ class UserOrganizationSerializer(OrganizationPageSerializer):
 
     contracts = serializers.SerializerMethodField()
 
+    @extend_schema_field(ContractPageSerializer(many=True))
     def get_contracts(self, instance):
         """Get the contracts for the organization for the user"""
         contracts = (
@@ -264,7 +265,7 @@ def get_username(self, instance):
     def get_grants(self, instance):
         return instance.get_all_permissions()
 
-    @extend_schema_field(list[dict])
+    @extend_schema_field(UserOrganizationSerializer(many=True))
     def get_b2b_organizations(self, instance):
         """Get the organizations for the user"""
         if instance.is_anonymous: