📝 Document OAS changes in Klanten API spec

issue: #18
maykinmedia · Nov 15, 2021 · 2f0f05b · 2f0f05b
1 parent cdcefc2
commit 2f0f05b
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 6 deletions.
diff --git a/src/openklant/components/klanten/api/schema.py b/src/openklant/components/klanten/api/schema.py
@@ -22,13 +22,18 @@
 * Zaken API *(optioneel)*
 * Documenten API *(optioneel)*
 
+**API specificatie afwijkingen**
+
+Afwijkingen in de API specificatie ten opzichte van de referentie API specificatie
+zijn aangemerkt met ***AFWIJKING:**
+
 **Autorisatie**
 
 Deze API vereist autorisatie. Je kan de
 [token-tool](https://zaken-auth.vng.cloud/) gebruiken om JWT-tokens te
 genereren.
 
-** Notificaties
+**Notificaties**
 
 {notification_documentation(KANAAL_KLANTEN)}
 

diff --git a/src/openklant/components/klanten/api/serializers.py b/src/openklant/components/klanten/api/serializers.py
@@ -21,6 +21,7 @@
     VerblijfsAdres,
     Vestiging,
 )
+from openklant.utils.api_spec import mark_oas_difference
 
 logger = logging.getLogger(__name__)
 
@@ -308,6 +309,11 @@ def __init__(self, *args, **kwargs):
         value_display_mapping = add_choice_values_help_text(KlantType)
         self.fields["subject_type"].help_text += f"\n\n{value_display_mapping}"
 
+        # Document
+        self.fields["aanmaakkanaal"].help_text = mark_oas_difference(
+            self.fields["aanmaakkanaal"].help_text
+        )
+
     def validate(self, attrs):
         validated_attrs = super().validate(attrs)
         subject = validated_attrs.get("subject", None)

diff --git a/src/openklant/components/klanten/openapi.yaml b/src/openklant/components/klanten/openapi.yaml
@@ -30,6 +30,14 @@ info:
     * Documenten API *(optioneel)*
 
 
+    **API specificatie afwijkingen**
+
+
+    Afwijkingen in de API specificatie ten opzichte van de referentie API specificatie
+
+    zijn aangemerkt met ***AFWIJKING:**
+
+
     **Autorisatie**
 
 
@@ -40,7 +48,7 @@ info:
     genereren.
 
 
-    ** Notificaties
+    **Notificaties**
 
 
     Deze API publiceert notificaties op het kanaal `klanten`.
@@ -1016,7 +1024,8 @@ components:
           nullable: true
         aanmaakkanaal:
           title: Aanmaakkanaal
-          description: Het communicatiekanaal waarlangs de klant is aangemaakt.
+          description: '***AFWIJKING:** Het communicatiekanaal waarlangs de klant
+            is aangemaakt.'
           type: string
           maxLength: 50
       discriminator:

diff --git a/src/openklant/components/klanten/resources.md b/src/openklant/components/klanten/resources.md
@@ -43,7 +43,7 @@ Uitleg bij mogelijke waarden:
 * `natuurlijk_persoon` - Natuurlijk persoon
 * `niet_natuurlijk_persoon` - Niet-natuurlijk persoon
 * `vestiging` - Vestiging | string | nee | CRUD |
-| aanmaakkanaal | Het communicatiekanaal waarlangs de klant is aangemaakt. | string | nee | CRUD |
+| aanmaakkanaal | ***AFWIJKING:** Het communicatiekanaal waarlangs de klant is aangemaakt. | string | nee | CRUD |
 
 ## VerblijfsAdres
 

diff --git a/src/openklant/components/klanten/swagger2.0.json b/src/openklant/components/klanten/swagger2.0.json
@@ -2,7 +2,7 @@
     "swagger": "2.0",
     "info": {
         "title": "Klanten API",
-        "description": "Een API om klanten te benaderen.\n\nEen API om zowel klanten te registreren als op te vragen. Een klant\nis een natuurlijk persoon, niet-natuurlijk persoon (bedrijf) of vestiging\nwaarbij het gaat om niet geverifieerde gegevens. De Klanten API kan\nzelfstandig of met andere API's samen werken om tot volledige functionaliteit\nte komen.\n\n**Afhankelijkheden**\n\nDeze API is afhankelijk van:\n\n* Autorisaties API\n* Notificaties API\n* Zaken API *(optioneel)*\n* Documenten API *(optioneel)*\n\n**Autorisatie**\n\nDeze API vereist autorisatie. Je kan de\n[token-tool](https://zaken-auth.vng.cloud/) gebruiken om JWT-tokens te\ngenereren.\n\n** Notificaties\n\nDeze API publiceert notificaties op het kanaal `klanten`.\n\n**Main resource**\n\n`klant`\n\n\n\n**Kenmerken**\n\n* `subject_type`: Type van de `subject`.\n\n**Resources en acties**\n\n\n**Handige links**\n\n* [Documentatie](https://zaakgerichtwerken.vng.cloud/standaard)\n* [Zaakgericht werken](https://zaakgerichtwerken.vng.cloud)\n",
+        "description": "Een API om klanten te benaderen.\n\nEen API om zowel klanten te registreren als op te vragen. Een klant\nis een natuurlijk persoon, niet-natuurlijk persoon (bedrijf) of vestiging\nwaarbij het gaat om niet geverifieerde gegevens. De Klanten API kan\nzelfstandig of met andere API's samen werken om tot volledige functionaliteit\nte komen.\n\n**Afhankelijkheden**\n\nDeze API is afhankelijk van:\n\n* Autorisaties API\n* Notificaties API\n* Zaken API *(optioneel)*\n* Documenten API *(optioneel)*\n\n**API specificatie afwijkingen**\n\nAfwijkingen in de API specificatie ten opzichte van de referentie API specificatie\nzijn aangemerkt met ***AFWIJKING:**\n\n**Autorisatie**\n\nDeze API vereist autorisatie. Je kan de\n[token-tool](https://zaken-auth.vng.cloud/) gebruiken om JWT-tokens te\ngenereren.\n\n**Notificaties**\n\nDeze API publiceert notificaties op het kanaal `klanten`.\n\n**Main resource**\n\n`klant`\n\n\n\n**Kenmerken**\n\n* `subject_type`: Type van de `subject`.\n\n**Resources en acties**\n\n\n**Handige links**\n\n* [Documentatie](https://zaakgerichtwerken.vng.cloud/standaard)\n* [Zaakgericht werken](https://zaakgerichtwerken.vng.cloud)\n",
         "contact": {
             "url": "https://zaakgerichtwerken.vng.cloud",
             "email": "standaarden.ondersteuning@vng.nl"
@@ -1044,7 +1044,7 @@
                 },
                 "aanmaakkanaal": {
                     "title": "Aanmaakkanaal",
-                    "description": "Het communicatiekanaal waarlangs de klant is aangemaakt.",
+                    "description": "***AFWIJKING:** Het communicatiekanaal waarlangs de klant is aangemaakt.",
                     "type": "string",
                     "maxLength": 50
                 }