Produits Entr'ouvert » Passerelle

(possibilité aussi de gérer les deux, le schéma intégral dans la situation où il existerait déjà (et on pointerait alors vers celui-ci pour la doc), le schéma généré pour les cas simples et courants)

On devrait s'inspirer d'OpenAPI, normalement ils séparent les chemins des actions (GET, POST, PUT, etc..) et pour chaque action on éventuellement un request_body (décrit selon son type mime, souvent application/json) et des paramètres (pouvant venir du chemin si templaté, d'un header, de la query string ou d'un cookie), ça me semble coller.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject

À noter les paramètres peuvent être décrit au niveau du chemin ou au niveau de l'action (sous-niveau), on pourrait reprendre tel quel le schéma pour l'objet "Path" d'OpenAPI (on aura pas trop de mal à générer du swagger/openapi complet à terme.).

Bien sûr on ne casserai pas l'API endpoint actuelle, juste on y ajouterai un paramètre "openapi", et on y implémenterai que ce qui nous sert en simplifiant, exemple sur DPark:

@endpoint(openapi={
    'path': '/address-eligibility/',
    'get': {'description': _('Verify eligibility of an address')},
    'parameters': [
        {
          'name': 'address_sticode',
          'in': 'query',
          'description': _('Address STI code'),
          'required': True,
          'schema': {'type': 'string'},
        },
       {
          'name': 'address_zipcode',
          'in': 'query',
          'description': _('Address ZIP code'),
          'required': True,
          'schema': {'type': 'string'},
        }, 
       {
          'name': 'address_locality',
          'in': 'query',
          'description': _('Address locality'),
          'required': True,
          'schema': {'type': 'string'},
        },
     }})
....

On peut générer name et pattern à partir de path et éventuellement d'une regexp filée dans schema, le but c'est d'avoir un chemin de migration vers OpenAPI sans continuer à trop inventer autour.

Autre exemple pour un POST toujours du DPark:

@endpoint(openapi={
    'path': '/register/',
    'post': {
       'description': _('Register a subscription application'),
       'request_body': {
           'schema': {
                'application/json': REGISTER_SCHEMA <-- ici on pourrait simplifier et mettre directement le schéma dans request_body ou mettre un clé schema directement dans le dico de "post" 
           }
       }
    }

En plus de documenter on pourrait aussi directement implémenter la validation des requêtes avec les différents schémas.

On a des paramètres à @endpoint qui seraient aujourd'hui incompatibles ? Mon idée derrière étant que si on part dans cette direction à un moment on voudra @endpoint(path='...', 'post': ...) (dégager le openapi), et que si c'est jouable dès maintenant d'avoir ainsi les paramètres à la racine, on devrait directement commencer ainsi.

Aussi, j'aimerais voir dans quelle mesure ça impose des trucs qu'on va trouver redondant à mentionner, genre :

          'in': 'query',
          'required': True,
          'schema': {'type': 'string'},

Aujourd'hui on crée ce qu'on peut par introspection (genre la liste des paramètres, s'ils sont obligatoire ou pas), et je trouve que c'est quelque chose d'utile à conserver.

Dans #27653, rebasé ma branche sur celle-ci et adapté mes endpoints, ça fait le taf.