Documentez votre API Rest Ruby On Rails avec Swagger

Documentez son API est indispensable quelque soit le projet, et avoir rapidement accès à ses endpoints pour tester nos développement l’est tout autant. La solution la plus populaire est alors d’utiliser Swagger.

Nous allons donc mettre en place cela pour votre API Ruby On Rails, à l’aide de RSWAG

Pré-requis :

Avoir une application Ruby on Rails (vous pouvez aller lire mon article ici pour créer votre première application)

Les étapes :

1. Installation
2. Génération automatique de la documentation
3. Configuration des CORS
4. Pour aller plus loin

Step 1 : Installation

Au sein de votre fichier GemFile ajoutez ceci :

group :development, :test do
  gem 'rspec-rails'
  gem 'rswag-specs'
end

gem 'rswag'
gem 'rswag-api'
gem 'rswag-ui'

Une fois votre GemFile mis à jour faites dans votre terminal :

$ bundle install

$ rails g rspec:install 
$ rails g rswag:install

Step 2 : Génération de la documentation

Créons maintenant notre documentation basé sur l’un de nos controlleur.

Si dans mon projet, j’ai un controller nommé Users dans mon dossier controller/api/v1/users

controller
   |__ api
       |___ v1
            |___ users_controller.rb
   

La documentation de mon controller Users générer automatiquement ma documentation comme cela :

rails generate rspec:swagger API::V1::Users

Lancez ensuite la commande suivante :

rake rswag:specs:swaggerize

Et rendez-vous sur http://localhost:3000/api-docs/index.html

Nous avons notre documentation Swagger ! Passons maintenant à l’activation des Cors pour que vous puissiez faire vos appels à l’Api à partir de votre nouvelle doc’ !

Vous n’aurez besoin de configurer CORS que lorsque vous utilisez Rails comme API. Si vous construisez des applications monolithe Ruby on Rails traditionnelles, vous n’aurez pas besoin de le faire. 

Step 3 : Vérifications des CORS

Nous allons vérifier si nos CORS sont bien configurés afin que vous puissiez faire les appels à partir du Swagger, vers votre API rails.

Vous n’aurez besoin de configurer CORS que lorsque vous utilisez Rails comme API. Si vous construisez des applications monolithe Ruby on Rails traditionnelles, vous n’aurez pas besoin de le faire. Pourquoi?  Tout simplement parce que CORS bloque les appels d’origines différentes. Dans le cas d’une application monolithique Ruby on Rails, le front end et le back end sont à la même origine. 

Mais lorsque vous utilisez l’application Rails uniquement en tant qu’API, il est nécéssaire de les configurer puisqu’ici ce sera Swagger qui fera un appel vers notre application.

Ajoutez donc ceci au sein de votre GemFile :

gem 'rack-cors'

Puis allez dans votre fichier config/initializers/cors.rb et ajoutez ceci :

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'http://localhost:3000'
    resource '*', headers: :any, methods: [:get, :post, :put, :delete]
  end
end

La configuration ci-dessus autorise donc les HTTP GET POST PUT et DELETE depuis ‘http://localhost:3000’ vers votre application Rails. Vous pouvez également configurer des règles CORS distinctes par point de terminaison. Par exemple: 

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'http://example.com:80'
    resource '/orders',
      :headers => :any,
      :methods => [:post]
    resource '/users',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head]
  end
end

Cette configuration n’autorisera que les HTTP POSTappels vers le point de terminaison /order et toutes les méthodes HTTP vers tout autre point de terminaison. 

Attention : Ne pas mettre origins: '*' cela permet à n’importe qui sur internet de se connecter à votre interface de programmation d’applications ! C’est donc un risque pour la sécurité. À moins que votre API ne soit par conception ouverte à tout le monde, vous ne devriez vraiment pas définir de caractère générique comme origine.

Pour allez plus loin

Maintenant configurons correctement notre Swagger nouvellement généré grâce à RSWAG, configurons tout cela.

Amélioration de notre Documentation

Lors de nos différentes manipulations, plusieurs fichiers ont été générés, et nous allons les parcourir rapidement :

spec/requests/users_spec.rb

C’est ici qu’il faudra décrire votre API pour les différents endpoints de votre controller. Une documentation basique est générée , mais vous pouvez la personnaliser en ajoutant des tags, de nouvelles réponses, des exemples etc.

Exemple de création d’un nouveau User :

   post('create a new  member') do
      tags "Users"
      consumes "application/json"
      parameter name: :users, in: :body, schema: {
        type: :object,
        properties: {
          memberId: { type: :string },
          firstname: { type: :string },
          lastname: { type: :string },
          pseudo: { type: :string },
          email: { type: :string },
          phoneNumber: { type: :integer },
          password: { type: :string },
          address: { type: :string },
          city: { type: :string },
          zipcode: { type: :string },
          country: { type: :string },
        },
        required: %w[memberId address city country email firstname lastname password phoneNumber pseudo zipcode]
      }
      response "201", "created" do
        let(:members) { {
          memberId: 10, address: "test", city: "Paris",
          country: "France", email: "test", firstname:  "Sarah", lastname: "B",
          password: "A hash", phoneNumber: "0600000000", pseudo: "beanyovertech", zipcode: "93400"
        } }
        run_test!
      end
    end
  end

spec/swagger_helper.rb

c’est ici que vous allez pouvoir configurer swagger coté serveur. Exemple :

# frozen_string_literal: true

require 'rails_helper'

RSpec.configure do |config|
  config.swagger_root = Rails.root.join('swagger').to_s
  config.swagger_docs = {
    'v1/swagger.yaml' => {
      openapi: '3.0.1',
      info: {
        title: 'API V1',
        version: 'v1',
      },
      paths: {},
      servers: [
        {
          url: 'http://{defaultHost}',
          variables: {
            defaultHost: {
              default: 'localhost:3000'
            }
          }
        }
      ]
    }
  }
  config.swagger_format = :yaml
end

swagger/v1/swagger.yml

c’est tout simplement le fichier qui sera appelé et qui se génère à partir du fichier swagger_helper.rb