greco: add description to endpoints (#52094)

passerelle/contrib/greco/models.py

@@ -76,6 +76,7 @@ class Greco(BaseResource):
     wsdl_url = models.CharField(_('WSDL URL'), max_length=256)  # not URLField, it can be file://
     verify_cert = models.BooleanField(default=True, verbose_name=_('Check HTTPS Certificate validity'))
 
+    hide_description_fields = ['token_authorization']
     category = _('Business Process Connectors')
 
     class Meta:
@@ -220,14 +221,30 @@ class Greco(BaseResource):
         if self.get_client().service.communicationTest('ping') is None:
             raise Exception('empty answer to communication test')
 
-    @endpoint(perm='can_access')
+    @endpoint(
+        perm='can_access',
+        description=_('Communication test'),
+        long_description='''Response :
+        {"data": "…[ping]", "err": 0}''',
+        display_order=1,
+    )
     def ping(self, request):
         resp = self.get_client().service.communicationTest('ping')
         if resp is None:
             raise APIError('empty response from communicationTest()')
         return {'data': resp}
 
-    @endpoint(perm='can_access', methods=['post'])
+    @endpoint(
+        perm='can_access',
+        methods=['post'],
+        description=_('Create a demand'),
+        long_description='''Payload JSON :
+        { "iddemande": "…", "description": "…", "domaineobjettype": "…", "datecreation": "…", "datedepot": "…", "danger": "…", "mediareponse": "…", "priorite": "…", "application": "…", "beneficiaire_civilite": "…", "beneficiaire_nom": "…", "beneficiaire_prenom": "…", "beneficiaire_email": "…", "beneficiaire_mobile": "…", "beneficiaire_telephone": "…", "beneficiaire_fax": "…", "beneficiaire_numerovoie": "…", "beneficiaire_voie": "…", "beneficiaire_codefuvvoie": "…", "beneficiaire_coderivolivoie": "…", "beneficiaire_complement": "…", "beneficiaire_codepostal": "…", "beneficiaire_commune": "…", "beneficiaire_organisation": "…", "beneficiaire_typetiers": "…", "localisation_numerovoie": "…", "localisation_voie": "…", "localisation_codefuvvoie": "…", "localisation_coderivolivoie": "…", "localisation_complement": "…", "localisation_commune": "…", "localisation_voiesecante": "…", "localisation_codefuvvoiesecante": "…", "localisation_coderivolivoiesecante": "…", "localisation_xgeoloc": "…", "localisation_ygeoloc": "…", "transmetteur_civilite": "…", "transmetteur_nom": "…", "transmetteur_prenom": "…", "transmetteur_email": "…", "transmetteur_mobile": "…", "transmetteur_telephone": "…", "transmetteur_fax": "…", "transmetteur_service": "…", "fichier1": {"filename": "….…", "content_type": "…/…", "content": "…base64…" }, "fichier2": { … } }
+
+        Response :
+        {"data": {"application": "…", "etat": "1 - Créée", "iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}''',
+        display_order=2,
+    )
     def create(self, request):
         # get creation fields from payload
         try:
@@ -250,7 +267,13 @@ class Greco(BaseResource):
         '''used in greco_detail.html template'''
         return list_schema_fields(CREATION_SCHEMA)
 
-    @endpoint(perm='can_access')
+    @endpoint(
+        perm='can_access',
+        description=_('Get a demand'),
+        long_description='''Response :
+        {"data": {"commentaireReponse": null, "comptesRendus": null, "dateResolutionEffective": null, "dateResolutionPrevue": "YYYY-MM-DD", "etat": "1 - Créée", "groupeResponsable": null, "iddemande": "…", "idgreco": "…", "motifsrejet": null, "suiteDonnee": null}, "err": 0}''',
+        display_order=3,
+    )
     def status(self, request, idgreco, iddemande=None):
         resp = self.get_client().service.consulter(
             {
@@ -262,7 +285,13 @@ class Greco(BaseResource):
             raise APIError('empty response from status()')
         return {'data': sudsobject_to_dict(resp)}
 
-    @endpoint(perm='can_access')
+    @endpoint(
+        perm='can_access',
+        description=_('Get mail response to a demand'),
+        long_description='''Response :
+        {"data": {"etat": null, "idgreco": "…", "iddemande": "…", "motifsrejet": null, "message": "…"}, "err": 0}''',
+        display_order=4,
+    )
     def answer(self, request, idgreco, iddemande, code=None):
         params = {
             'idgreco': idgreco,
@@ -275,7 +304,15 @@ class Greco(BaseResource):
             raise APIError('empty response from consulter()')
         return {'data': sudsobject_to_dict(resp)}
 
-    @endpoint(name='add-information', perm='can_access', methods=['get', 'post', 'put', 'patch'])
+    @endpoint(
+        perm='can_access',
+        methods=['get', 'post', 'put', 'patch'],
+        name='add-information',
+        description=_('Provide additional information to a demand'),
+        long_description='''Response :
+        {"data": {"iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}''',
+        display_order=5,
+    )
     def add_information(self, request, iddemande=None, idgreco=None, information=None):
         if request.body:
             payload = json_loads(request.body)
@@ -295,7 +332,14 @@ class Greco(BaseResource):
             raise APIError('empty response from ajouterComplementInformation()')
         return {'data': sudsobject_to_dict(resp)}
 
-    @endpoint(perm='can_access', methods=['get', 'post', 'put', 'patch'])
+    @endpoint(
+        perm='can_access',
+        methods=['get', 'post', 'put', 'patch'],
+        description=_('Remind a demand'),
+        long_description='''Response :
+        {"data": {"iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}''',
+        display_order=6,
+    )
     def update(self, request, iddemande=None, idgreco=None, comment=None):
         if request.body:
             payload = json_loads(request.body)
@@ -315,7 +359,15 @@ class Greco(BaseResource):
             raise APIError('empty response from relancer()')
         return {'data': sudsobject_to_dict(resp)}
 
-    @endpoint(perm='can_access', methods=['post'], name='add-confirmation')
+    @endpoint(
+        perm='can_access',
+        methods=['post'],
+        name='add-confirmation',
+        description=_('Update number of confirmations (+1) related to a demand'),
+        long_description='''Response :
+        {"data": {"iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}''',
+        display_order=7,
+    )
     def add_confirmation(self, request):
         payload = json_loads(request.body)
         if not isinstance(payload, dict):

passerelle/contrib/greco/templates/greco/greco_detail.html

@@ -1,80 +0,0 @@
-{% extends "passerelle/manage/service_view.html" %}
-{% load i18n passerelle %}
-
-{% block description %}
-{% if object.description %}{{object.description|linebreaks}}{% endif %}
-{% endblock %}
-
-{% block endpoints %}
-<ul class="endpoints">
-    <li class="get-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="ping" as ping %}
-        <a class="example-url" href="{{ ping }}">{{ ping }}</a>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": "…[ping]", "err": 0}
-        </samp>
-    </li>
-    <li class="post-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="create" as create %}
-        <a class="example-url" href="{{ create }}">{{ create }}</a>
-        <br />
-        <span class="params-title">{% trans 'JSON payload:' %}</span>
-        <div class="body-schemas"><samp>
-          { {% for field in object.creation_fields %}"{{ field }}":&nbsp;"…", {% endfor %}
-          "fichier1":&nbsp;{"filename":&nbsp;"….…", "content_type":&nbsp;"…/…", "content":&nbsp;"…base64…" },
-          "fichier2":&nbsp;{ … }
-          }
-          </samp>
-          </div>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": {"application": "…", "etat": "1 - Créée", "iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}
-        </samp>
-    </li>
-    <li class="get-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="status" as status %}
-        <a class="example-url" href="{{ status }}?idgreco=…&iddemande=…">{{ status }}?idgreco=…[&iddemande=…]</a>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": {"commentaireReponse": null, "comptesRendus": null, "dateResolutionEffective": null, "dateResolutionPrevue": "YYYY-MM-DD",
-                    "etat": "1 - Créée", "groupeResponsable": null, "iddemande": "…", "idgreco": "…", "motifsrejet": null, "suiteDonnee": null},
-          "err": 0}
-        </samp>
-    </li>
-    <li class="get-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="answer" as answer %}
-        <a class="example-url" href="{{ answer }}?idgreco=…&iddemande=…">{{ answer }}?idgreco=…&iddemande=…&code=…</a>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": {"etat": null, "idgreco": "…", "iddemande": "…", "motifsrejet": null, "message": "…"},
-          "err": 0}
-        </samp>
-    </li>
-    <li class="post-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="add-information" as addinfo %}
-        <a class="example-url" href="{{ addinfo }}">{{ addinfo }}</a>
-        <br />
-        {% trans 'JSON payload:' %} <samp>
-          {"idgreco": "…", "iddemande": "…", "information": "…"}
-        </samp>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": {"iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}
-        </samp>
-    </li>
-    <li class="post-method">
-        {% url "generic-endpoint" connector="greco" slug=object.slug endpoint="update" as update %}
-        <a class="example-url" href="{{ update }}">{{ update }}</a>
-        <br />
-        <span class="params-title">{% trans 'JSON payload:' %}</span>
-        <div class="body-schemas"><samp>
-          {"idgreco": "…", "iddemande": "…", "comment": "…"}
-        </samp></div>
-        <br />
-        {% trans 'Response:' %} <samp>
-          {"data": {"iddemande": "…", "idgreco": "…", "motifsrejet": null}, "err": 0}
-        </samp>
-    </li>
-</ul>
-{% endblock %}