[NDH-840] Centralizing API Documentation Content (#399)

* created centralized doc

* adding content to views

* adding filter content

* adding unit tests

Author: sachin-panayil

backend/npdfhir/documentation_content.py

@@ -0,0 +1,157 @@
+class docs:
+    # Centralized namespace for all NPD API documentation content
+
+    class constants:
+        # Constant strings that appear throughout content building
+
+        sort_order_text = "Default sort order: "
+
+    class filters:
+        # Help text for filter parameters, organized by FHIR resource
+
+        class practitioner:
+            name = (
+                "Filter by practitioner name (first, middle, last, or full name). "
+                "Name filter accepts websearch syntax."
+            )
+            gender = "Filter by practitioner gender"
+            identifier = (
+                "Filter by practitioner identifier (NPI or other). Format: value or system|value"
+            )
+            type = (
+                "Filter by practitioner type/taxonomy. "
+                "Practitioner type filter accepts websearch syntax."
+            )
+
+        class organization:
+            name = "Filter by organization name"
+            identifier = (
+                "Filter by organization identifier (NPI, EIN, or other). "
+                "Format: value or system|value"
+            )
+            type = "Filter by organization type/taxonomy"
+
+        class location:
+            name = "Filter by location name"
+            near = (
+                "Filter by distance from a point expressed as "
+                "[latitude]|[longitude]|[distance]|[units]. "
+                "If no units are provided, km is assumed."
+            )
+
+        class endpoint:
+            name = "Filter by endpoint name"
+            connection_type = "Filter by endpoint connection type"
+            payload_type = "Filter by endpoint payload type"
+            status = "Filter by endpoint status"
+
+        class practitioner_role:
+            active = "Filter by active status"
+            role = "Filter by provider role code"
+            specialty = "Filter by Nucc/Snomed specialty code"
+
+        class address:
+            full = "Filter by any part of address. Address filter accepts websearch syntax."
+            city = "Filter by city name"
+            state = "Filter by state (2-letter abbreviation)"
+            postalcode = "Filter by postal code/zip code"
+            use = "Filter by address use type"
+
+    class endpoints:
+        # Descriptions for API endpoints
+
+        class practitioner:
+            viewset = "ViewSet for FHIR Practitioner resources"
+            list_description = (
+                "Query a list of healthcare providers, represented as a "
+                "bundle of FHIR Practitioner resources"
+            )
+            default_sort = "ascending last name, first name"
+            retrieve_description = "Query a specific provider as a FHIR Practitioner resource"
+            list_response = (
+                "Successfully retrieved FHIR Bundle resource of FHIR Practitioner resources"
+            )
+            retrieve_response = "Successfully retrieved FHIR Practitioner resource"
+
+        class practitioner_role:
+            viewset = "ViewSet for FHIR PractitionerRole resources"
+            list_description = (
+                "Query a list of relationships between providers, healthcare "
+                "organizations, and practice locations, represented as a "
+                "bundle of FHIR PractitionerRole resources"
+            )
+            default_sort = "ascending by location name"
+            retrieve_description = (
+                "Query a specific relationship between providers, healthcare "
+                "organizations, and practice locations, represented as a "
+                "FHIR PractitionerRole resource"
+            )
+            list_response = (
+                "Successfully retrieved FHIR Bundle resource of FHIR PractitionerRole resources"
+            )
+            retrieve_response = "Successfully retrieved FHIR PractitionerRole resource"
+
+        class organization:
+            viewset = "ViewSet for FHIR Organization resources"
+            list_description = (
+                "Query a list of organizations, represented as a bundle "
+                "of FHIR Organization resources"
+            )
+            default_sort = "ascending by organization name"
+            retrieve_description = (
+                "Query a specific organization, represented as a FHIR Organization resource"
+            )
+            list_response = (
+                "Successfully retrieved FHIR Bundle resource of FHIR Organization resources"
+            )
+            retrieve_response = "Successfully retrieved FHIR Organization resource"
+
+        class organization_affiliation:
+            viewset = "ViewSet for FHIR EHR Vendor to Organization relationships"
+            list_description = (
+                "Query a list of EHR vendor to organization relationships, "
+                "represented as a bundle of FHIR OrganizationAffiliation "
+                "resources"
+            )
+            default_sort = "ascending by organization name"
+            retrieve_description = (
+                "Query a specific EHR vendor to organization relationship, "
+                "represented as a FHIR OrganizationAffiliation resource"
+            )
+            list_response = (
+                "Successfully retrieved FHIR Bundle resource of "
+                "FHIR OrganizationAffiliation resources"
+            )
+            retrieve_response = "Successfully retrieved FHIR OrganizationAffiliation resource"
+
+        class location:
+            viewset = "ViewSet for FHIR Location resources"
+            list_description = (
+                "Query a list of healthcare practice locations, represented "
+                "as a bundle of FHIR Location resources"
+            )
+            default_sort = "ascending by location name"
+            retrieve_description = (
+                "Query a specific healthcare practice location as a FHIR Location resource"
+            )
+            list_response = "Successfully retrieved FHIR Bundle resource of FHIR Location resources"
+            retrieve_response = "Successfully retrieved FHIR Location resource"
+
+        class endpoint:
+            viewset = "ViewSet for FHIR Endpoint resources"
+            list_description = (
+                "Query a list of interoperability endpoints, represented "
+                "as a bundle of FHIR Endpoint resources"
+            )
+            default_sort = "ascending by endpoint instance name"
+            retrieve_description = "Query a specific endpoint as a FHIR Endpoint resource"
+            list_response = "Successfully retrieved FHIR Bundle resource of FHIR Endpoint resources"
+            retrieve_response = "Successfully retrieved FHIR Endpoint resource"
+
+        class capability_statement:
+            viewset = "ViewSet for FHIR CapabilityStatement resource"
+            get_description = (
+                "Query metadata about this FHIR instance, represented as "
+                "FHIR CapabilityStatement resource"
+            )
+            get_response = "Successfully retrieved FHIR CapabilityStatement resource"

backend/npdfhir/filters/endpoint_filter_set.py

@@ -1,26 +1,32 @@
 from django_filters import rest_framework as filters
 
+from ..documentation_content import docs
 from ..models import EndpointInstance
 
 
 class EndpointFilterSet(filters.FilterSet):
     name = filters.CharFilter(
-        field_name="name", lookup_expr="icontains", help_text="Filter by name"
+        field_name="name",
+        lookup_expr="icontains",
+        help_text=docs.filters.endpoint.name,
     )
 
     connection_type = filters.CharFilter(
         field_name="endpoint_connection_type__id",
         lookup_expr="icontains",
-        help_text="Filter by connection type",
+        help_text=docs.filters.endpoint.connection_type,
     )
 
     payload_type = filters.CharFilter(
         field_name="endpointinstancetopayload__payload_type__id",
         lookup_expr="icontains",
-        help_text="Filter by payload type",
+        help_text=docs.filters.endpoint.payload_type,
     )
 
-    status = filters.CharFilter(method="filter_status", help_text="Filter by status")
+    status = filters.CharFilter(
+        method="filter_status",
+        help_text=docs.filters.endpoint.status,
+    )
 
     # We don't have a concept of endpoint organization at the moment
     # organization = filters.CharFilter(

backend/npdfhir/filters/location_filter_set.py

@@ -5,40 +5,52 @@
 from django.contrib.gis.measure import D
 from django.db.models import F
 
+from ..documentation_content import docs
 from ..mappings import addressUseMapping
 from ..models import Location
 
 
 class LocationFilterSet(filters.FilterSet):
     name = filters.CharFilter(
-        field_name="name", lookup_expr="contains", help_text="Filter by location name"
+        field_name="name",
+        lookup_expr="contains",
+        help_text=docs.filters.location.name,
     )
 
     organization_type = filters.CharFilter(
-        method="filter_organization_type", help_text="Filter by organization type"
+        method="filter_organization_type",
+        help_text=docs.filters.organization.type,
     )
 
-    address = filters.CharFilter(method="filter_address", help_text="Filter by any part of address")
+    address = filters.CharFilter(
+        method="filter_address",
+        help_text=docs.filters.address.full,
+    )
 
-    address_city = filters.CharFilter(method="filter_address_city", help_text="Filter by city name")
+    address_city = filters.CharFilter(
+        method="filter_address_city",
+        help_text=docs.filters.address.city,
+    )
 
     address_state = filters.CharFilter(
-        method="filter_address_state", help_text="Filter by state (2-letter abbreviation)"
+        method="filter_address_state",
+        help_text=docs.filters.address.state,
     )
 
     address_postalcode = filters.CharFilter(
-        method="filter_address_postalcode", help_text="Filter by postal code/zip code"
+        method="filter_address_postalcode",
+        help_text=docs.filters.address.postalcode,
     )
 
     address_use = filters.ChoiceFilter(
         method="filter_address_use",
         choices=addressUseMapping.to_choices(),
-        help_text="Filter by address use type",
+        help_text=docs.filters.address.use,
     )
 
     near = filters.CharFilter(
         method="filter_distance",
-        help_text="Filter by distance from a point expressed as [latitude]|[longitude]|[distance]|[units]. If no units are provided, km is assumed.",
+        help_text=docs.filters.location.near,
     )
 
     class Meta:

backend/npdfhir/filters/organization_filter_set.py

@@ -2,39 +2,52 @@
 from django.db.models import Q
 from django_filters import rest_framework as filters
 
+from ..documentation_content import docs
 from ..mappings import addressUseMapping
 from ..models import OrganizationView
 from ..utils import parse_identifier_query
 
 
 class OrganizationFilterSet(filters.FilterSet):
-    name = filters.CharFilter(method="filter_name", help_text="Filter by organization name")
+    name = filters.CharFilter(
+        method="filter_name",
+        help_text=docs.filters.organization.name,
+    )
 
     identifier = filters.CharFilter(
         method="filter_identifier",
-        help_text="Filter by identifier (NPI, EIN, or other). Format: value or system|value",
+        help_text=docs.filters.organization.identifier,
     )
 
     organization_type = filters.CharFilter(
-        method="filter_organization_type", help_text="Filter by organization type/taxonomy"
+        method="filter_organization_type",
+        help_text=docs.filters.organization.type,
     )
 
-    address = filters.CharFilter(method="filter_address", help_text="Filter by any part of address")
+    address = filters.CharFilter(
+        method="filter_address",
+        help_text=docs.filters.address.full,
+    )
 
-    address_city = filters.CharFilter(method="filter_address_city", help_text="Filter by city name")
+    address_city = filters.CharFilter(
+        method="filter_address_city",
+        help_text=docs.filters.address.city,
+    )
 
     address_state = filters.CharFilter(
-        method="filter_address_state", help_text="Filter by state (2-letter abbreviation)"
+        method="filter_address_state",
+        help_text=docs.filters.address.state,
     )
 
     address_postalcode = filters.CharFilter(
-        method="filter_address_postalcode", help_text="Filter by postal code/zip code"
+        method="filter_address_postalcode",
+        help_text=docs.filters.address.postalcode,
     )
 
     address_use = filters.ChoiceFilter(
         method="filter_address_use",
         choices=addressUseMapping.to_choices(),
-        help_text="Filter by address use type",
+        help_text=docs.filters.address.use,
     )
 
     class Meta:

backend/npdfhir/filters/practitioner_filter_set.py

@@ -2,6 +2,7 @@
 from django.db.models import Q
 from django_filters import rest_framework as filters
 
+from ..documentation_content import docs
 from ..mappings import addressUseMapping, genderMapping
 from ..models import ProviderView
 from ..utils import parse_identifier_query
@@ -12,42 +13,49 @@ class PractitionerFilterSet(filters.FilterSet):
 
     identifier = filters.CharFilter(
         method="filter_identifier",
-        help_text="Filter by identifier (NPI or other). Format: value or system|value",
+        help_text=docs.filters.practitioner.identifier,
     )
 
     name = filters.CharFilter(
         method="filter_practitioner_name",
-        help_text="Filter by practitioner name (first, middle, last, or full name). Name filter accepts websearch syntax.",
+        help_text=docs.filters.practitioner.name,
     )
 
     gender = filters.ChoiceFilter(
-        method="filter_gender", choices=genderMapping.to_choices(), help_text="Filter by gender"
+        method="filter_gender",
+        choices=genderMapping.to_choices(),
+        help_text=docs.filters.practitioner.gender,
     )
 
     practitioner_type = filters.CharFilter(
         method="filter_practitioner_type",
-        help_text="Filter by practitioner type. Practitioner type filter accepts websearch syntax.",
+        help_text=docs.filters.practitioner.type,
     )
 
     address = filters.CharFilter(
         method="filter_address",
-        help_text="Filter by any part of address. Address filter accepts websearch syntax.",
+        help_text=docs.filters.address.full,
     )
 
-    address_city = filters.CharFilter(method="filter_address_city", help_text="Filter by city name")
+    address_city = filters.CharFilter(
+        method="filter_address_city",
+        help_text=docs.filters.address.city,
+    )
 
     address_state = filters.CharFilter(
-        method="filter_address_state", help_text="Filter by state (2-letter abbreviation)"
+        method="filter_address_state",
+        help_text=docs.filters.address.state,
     )
 
     address_postalcode = filters.CharFilter(
-        method="filter_address_postalcode", help_text="Filter by postal code/zip code"
+        method="filter_address_postalcode",
+        help_text=docs.filters.address.postalcode,
     )
 
     address_use = filters.ChoiceFilter(
         method="filter_address_use",
         choices=addressUseMapping.to_choices(),
-        help_text="Filter by address use type",
+        help_text=docs.filters.address.use,
     )
 
     class Meta: