🎯 Intention

On souhaite que nos applications disposent d’une documentation API.

L’objectif de la documentation API est que les dev soient plus autonomes.

On veut éviter la situation suivante :

sans doc API pour utiliser l’API, il faut soit contacter un dev back, soit regarder directement le code serveur et essayer de comprendre.

🚨 Si un développeur qui consomme votre API, vous pose des questions sur son fonctionnement, cela traduit un manque d’information dans la documentation.

<aside> ✅ Pré-requis

• Savoir écrire des tests
• Comprendre le fonctionnement d’une API
• Savoir ‣ (facultatif) </aside>

✅ Point clés

<aside> ⌛

Temps indicatif : 1h

</aside>

<aside> ⭐ Règle d’or

Pour toute question d’un consommateur de l’API (à l’oral, mail, slack) ⇒ on doit améliorer la documentation

</aside>

✨ La documentation API doit être accessible à l’adresse mon-site.com/api-docs

Raison :

Mise en place d’une convention pour éviter de devoir chercher l’url quand on arrive sur un projet. C’est aussi l’url par défaut fourni par la gem rswag (voir point #3).

🔒 La documentation API doit être accessible seulement par les administrateurs

• La documentation API doit être accessible seulement par les administrateurs de l’application (sauf si l’api est publique).

Raison :

On veut éviter de montrer notre API à une personne externe pour rendre plus difficile la recherche de faille.

# config/routes.rb

# ici :administrateur correspond à un Model Administrateur
# mais il est possible de le faire avec un utilisateur qui a un attribut administrateur

authenticate :administrateur do
  mount Rswag::Ui::Engine => '/api-docs'
  mount Rswag::Api::Engine => '/api-docs'
end

📦 Utiliser la gem rswag

• La documentation API est générée automatiquement avec la gem rswag via la commande rails rswag

• Générer des exemples de réponse de l’api avec la méthode examples

  

• Les paramètres envoyés à la requête doivent comporter un exemple de valeur

  

Raison :

Chez Captive, on test l’ensemble de nos fonctionnalités, donc l’ensemble de nos API. Avec l’utilisation de cette gem, on s’assure d’avoir une documentation API à jour.

# spec/requests/utilisateur_spec.rb

# frozen_string_literal: true

require 'swagger_helper'

RSpec.describe '/api/utilisateur', type: :request do
  let(:utilisateur) { create(:utilisateur) }
  let(:Authorization) { genere_token(utilisateur) }

  path '/api/utilisateur' do
    get "récupère les informations de l'utilisateur connecté" do
      tags 'Utilisateurs'
      consumes 'application/json'
      security [api_key: []]

			# On ajoute une description complète comprenant un exemple de valeur pour le paramètre 
			# On précise que la date est incluse pour éviter les confusions
			parameter description: "Retourne les utilisateurs créés à partir de la date (incluse) \\n
                                  Exemple : \\"YYYY-MM-DD\\"",
                name: :date_debut,
                in: :query,
                type: :string,
                required: false

      attr_reader :resultat

      response 200, 'success' do
        # La méthode examples permet de générer un exemple de réponse du point d'api
        examples 'application/json' => {
          id: 'b6ef772f-495f-4796-a247-23fa1871b381',
          email: '[email protected]',
          created_at: '2022-05-20T14:30:59.073+02:00',
          updated_at: '2022-05-20T14:30:59.140+02:00',
          prenom: 'Jean'
        }

        before(:each) do |example|
          submit_request(example.metadata)
          @resultat = JSON.parse(response.body)
        end

        it do
					expect(resultat['id']).to eq(utilisateur.id)
					expect(resultat['prenom']).to eq(utilisateur.prenom)
					expect(resultat['email']).to eq(utilisateur.email)
				end
      end
    end
  end
end