Petites amélioration de la documentation de l'api (#4815)

* Improve api documentation * simplify specs for webhook endpoints * Update spec/swagger_helper.rb Co-authored-by: Adrien Di Pasquale <[email protected]> * Update spec/swagger_helper.rb Co-authored-by: Adrien Di Pasquale <[email protected]> --------- Co-authored-by: Adrien Di Pasquale <[email protected]>
betagouv · Nov 19, 2024 · 3821418 · 3821418
1 parent a850ff5
commit 3821418
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 42 deletions.
diff --git a/docs/api/v1/description_api.md b/docs/api/v1/description_api.md
@@ -1,10 +1,9 @@
-L'API de RDV-Solidarités vous permet de lire des données dans notre base depuis votre logiciel.
+L'API de RDV Service Public permet à nos partenaires, comme par exemple Démarches Simplifiées et RDV Insertion,d'ajouter de la gestion de rendez-vous dans leurs applications métier.
+Elle peut aussi être utilisée pour synchroniser les calendriers des agents de votre administration avec ceux qu'ils ont sur leur compte RDV Service Public.
 
-Toutes les fonctionnalités de RDV-Solidarités ne sont pas encore disponibles via l’API. Contactez-nous si vous avez besoin de fonctionnalités qui ne sont pas encore présentes.
+L'API est disponible pour nos trois marques : RDV Service Public, RDV Solidarités, et RDV Aide Numérique.
 
-# Dépréciations
-
-**ATTENTION le champ `created_by` des `rdvs` et des `participations` est déprécié au profit du champ `created_by_type`.**
+Toutes les fonctionnalités de l'application ne sont pas encore disponibles via l’API. Contactez-nous si vous avez besoin de fonctionnalités qui ne sont pas encore présentes.
 
 # Requêtes
 
@@ -23,28 +22,15 @@ Les paramètres doivent respecter les formats suivants :
 - `DATE` : "YYYY-MM-DD" par exemple : "2021-10-21"
 - `TIME` : H:m[:s], par exemple : "10:30"
 
-# Versionnage
-
-L'API est versionnée. La version actuelle est 1.0 (référencée comme v1 dans les points de terminaison).
-
 # Routes
 
-Les points de terminaison de l'API sont accessibles par une route de la forme : `https://<domain>/api/<version>/<endpoint>`.
-
-Avec :
-
-- `version` est la version de l'API
-- `endpoint` est le nom du point de terminaison
-
-Par exemple, on aura : `https://<domain>/api/v1/absences`
-
 Pour la version production, les requêtes doivent être adressées à https://www.rdv-solidarites.fr et non à https://rdv-solidarites.fr.
 
 Pour la version démo, les requêtes doivent être adressées à https://demo.rdv-solidarites.fr.
 
 # Authentification
 
-Certains points de terminaison sont réservés aux agents authentifiés, dans la limite de leur rôle au sein de l'application.
+Presque tous les points de terminaison sont réservés aux agents authentifiés, dans la limite de leur rôle au sein de l'application.
 
 ## Headers d'authentification
 
@@ -145,9 +131,10 @@ La réponse contient en outre un objet meta qui indique le nombre total de pages
 }
 ```
 
-# Rate limiting
+# Dépréciations
+
+**ATTENTION le champ `created_by` des `rdvs` et des `participations` est déprécié au profit du champ `created_by_type`.**
 
-L'utilisation de l'API est limitée pour les points de terminaison sans authentification. Vous pouvez effectuer au maximum 50 appels par minutes. Si vous dépassez cette limite, une erreur 429 vous sera renvoyée et vous trouverez le temps que vous devez attendre avant de relancer une requête dans le header (`Retry-After`).
 
 # Codes de retour
 

diff --git a/spec/requests/api/v1/webhook_endpoints_request_spec.rb b/spec/requests/api/v1/webhook_endpoints_request_spec.rb
@@ -109,15 +109,16 @@
 
         run_test!
 
-        it { expect(WebhookEndpoint.count).to eq(webhook_endpoint_count_before + 1) }
-
-        it { expect(created_webhook_endpoint.organisation).to match(organisation) }
-
-        it { expect(created_webhook_endpoint.target_url).to eq(target_url) }
-
-        it { expect(created_webhook_endpoint.secret).to eq(secret) }
-
-        it { expect(created_webhook_endpoint.subscriptions).to match_array(%w[rdv user user_profile organisation motif lieu agent agent_role]) }
+        specify do
+          expect(WebhookEndpoint.count).to eq(webhook_endpoint_count_before + 1)
+
+          expect(created_webhook_endpoint.reload).to have_attributes(
+            organisation: organisation,
+            target_url: target_url,
+            secret: secret,
+            subscriptions: %w[rdv user user_profile organisation motif lieu agent agent_role]
+          )
+        end
       end
 
       it_behaves_like "an endpoint that returns 401 - unauthorized"
@@ -173,13 +174,14 @@
 
         run_test!
 
-        it { expect(webhook_endpoint.reload.organisation).to eq(other_organisation) }
-
-        it { expect(webhook_endpoint.reload.target_url).to eq(target_url) }
-
-        it { expect(webhook_endpoint.reload.secret).to eq(secret) }
-
-        it { expect(webhook_endpoint.reload.subscriptions).to eq(%w[rdv user user_profile organisation motif lieu agent agent_role]) }
+        specify do
+          expect(webhook_endpoint.reload).to have_attributes(
+            organisation: other_organisation,
+            target_url: target_url,
+            secret: secret,
+            subscriptions: %w[rdv user user_profile organisation motif lieu agent agent_role]
+          )
+        end
       end
 
       it_behaves_like "an endpoint that returns 401 - unauthorized"

diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb
@@ -52,7 +52,7 @@
     "v1/api.json" => {
       openapi: "3.0.1",
       info: {
-        title: "API RDV Solidarités",
+        title: "API de RDV Service Public",
         version: "v1",
         description: Rails.root.join("docs/api/v1/description_api.md").read,
       },
@@ -581,7 +581,11 @@
         },
         {
           name: "PublicLink",
-          description: "Désigne des liens publics de recherche d'un territoire. Ces liens permettent d'accéder directement à la recherche, préfiltrée sur un territoire donné.",
+          description:
+          <<~DESCRIPTION,
+            Utilisé pour faire la correspondance entre des ids externes et des liens de prises de RDV au sein d'un territoire. Ces liens permettent d'accéder directement à la recherche de créneaux pour une organisation donnée.
+            Cet endpoint est limité à 50 appels par minute par adresse IP.
+          DESCRIPTION
         },
         {
           name: "Absence",
@@ -600,9 +604,13 @@
           url: "https://demo.rdv-solidarites.fr",
           description: "Serveur de démo",
         },
+        {
+          url: "https://rdv.anct.gouv.fr",
+          description: "Serveur de production pour RDV Service Public",
+        },
         {
           url: "https://www.rdv-solidarites.fr",
-          description: "Serveur de production",
+          description: "Serveur de production pour RDV Solidarités",
         },
       ],
     },