From 27f3bafed5c434d7a3d9091077cbf4e88c61a32f Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <vdeniaud@entrouvert.com>
Date: Wed, 27 Nov 2019 17:01:07 +0100
Subject: [PATCH] base_adresse: move endpoint documentation to decorator
 (#11497)

---
 passerelle/apps/base_adresse/models.py        | 26 ++++++++++++++++---
 .../base_adresse/baseadresse_detail.html      | 19 --------------
 2 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/passerelle/apps/base_adresse/models.py b/passerelle/apps/base_adresse/models.py
index bd463677..30068f62 100644
--- a/passerelle/apps/base_adresse/models.py
+++ b/passerelle/apps/base_adresse/models.py
@@ -26,6 +26,10 @@ class BaseAdresse(BaseResource):
 
     category = _('Geographic information system')
 
+    api_description = _("The API is a partial view of OpenStreetMap's Nominatim "
+                        "own API; it currently doesn't support all parameters and "
+                        "is limited to the JSON format.")
+
     zipcode = models.CharField(
         max_length=600,
         blank=True,
@@ -34,7 +38,11 @@ class BaseAdresse(BaseResource):
     class Meta:
         verbose_name = _('Base Adresse Web Service')
 
-    @endpoint(pattern='(?P<q>.+)?$')
+    @endpoint(pattern='(?P<q>.+)?$',
+              description=_('Geocoding'),
+              parameters={
+                  'q': {'description': _('Address'), 'example_value': '169 rue du chateau, paris'}
+              })
     def search(self, request, q, zipcode='', lat=None, lon=None, **kwargs):
         if kwargs.get('format', 'json') != 'json':
             raise NotImplementedError()
@@ -68,7 +76,11 @@ class BaseAdresse(BaseResource):
 
         return result
 
-    @endpoint()
+    @endpoint(description=_('Reverse geocoding'),
+              parameters={
+                  'lat': {'description': _('Latitude'), 'example_value': 48.833708},
+                  'lon': {'description': _('Longitude'), 'example_value': 2.323349},
+              })
     def reverse(self, request, lat, lon, **kwargs):
         if kwargs.get('format', 'json') != 'json':
             raise NotImplementedError()
@@ -103,7 +115,15 @@ class BaseAdresse(BaseResource):
                     result['address']['road'] = value
         return result
 
-    @endpoint()
+    @endpoint(description=_('Streets from zipcode'),
+              parameters={
+                  'id': {'description': _('Get exactly one street')},
+                  'q': {'description': _("Street name")},
+                  'zipcode': {'description': _('Zipcode')},
+                  'page_limit': {'description': _('Maximum number of results to return'),
+                                 'example_value': 30},
+                  'distinct': {'description': _('Remove duplicate streets')},
+              })
     def streets(self, request, zipcode=None, q=None, id=None, distinct=True, page_limit=None):
         result = []
         if id is not None:
diff --git a/passerelle/apps/base_adresse/templates/base_adresse/baseadresse_detail.html b/passerelle/apps/base_adresse/templates/base_adresse/baseadresse_detail.html
index 069301cd..1a36bfda 100644
--- a/passerelle/apps/base_adresse/templates/base_adresse/baseadresse_detail.html
+++ b/passerelle/apps/base_adresse/templates/base_adresse/baseadresse_detail.html
@@ -10,25 +10,6 @@
 {% endif %}
 {% endblock %}
 
-{% block endpoints %}
-<p>
-{% blocktrans %}
-The API is a partial view of <a href="http://wiki.openstreetmap.org/wiki/Nominatim">Nominatim</a>
-own API; it currently doesn't support all parameters and is limited to the JSON
-format.
-{% endblocktrans %}
-</p>
-
-<ul>
-<li>{% trans 'Geocoding:' %} <a href="search?q=169 rue du chateau, paris&format=json"
-  >{{ site_base_uri }}{{ object.get_absolute_url }}search</a>?q=<i>q</i>&amp;format=json</li>
-<li>{% trans 'Reverse geocoding:' %} <a href="reverse?lat=48.833708&amp;lon=2.323349&amp;format=json"
-  >{{ site_base_uri }}{{ object.get_absolute_url }}reverse</a>?lat=<i>lat</i>&amp;lon=<i>lon</i>&amp;format=json</li>
-<li>{% trans 'Streets from zipcode:' %} <a href="streets?zipcode={{object.zipcode}}&amp;format=json"
-  >{{ site_base_uri }}{{ object.get_absolute_url }}streets</a>?zipcode=<i>zipcode</i>&amp;format=json</li>
-</ul>
-{% endblock %}
-
 {% block security %}
 <p>
 {% trans 'Accessing the listings is open.' %}