API Osuny

Contexte

L’API d’Osuny permet d’interagir avec l’instance de façon programmatique. Pour assurer la sécurité des échanges, on crée une app sur l’instance concernée, avec le chemin /admin/university/apps. Cette app génère un jeton secret, qu’il faut fournir pour utiliser les méthodes authentifiées de l’API.

https://demo.osuny.org/api/osuny/v1/

Documentation de l’API Osuny

La documentation de l’API est :

produite avec RSpec
transformée par la gem rswag
publiée au format OpenAPI
consultable avec swagger-ui (produit par Swagger)

Le workflow part des spécifiations dans le dossier spec.

- - - posts_spec.rb
  - websites_spec.rb
- osuny_spec.rb
rails_helper.rb
spec_helper.rb
swagger_helper.rb

spec/requests/osuny/v1/communication/websites/posts_spec.rb

require 'swagger_helper'

RSpec.describe 'Communication::Website::Post' do
  fixtures :all

  path '/communication/websites/{website_id}/posts' do
    get "Lists a website's posts" do
      tags 'Communication::Website::Post'
      security [{ api_key: [] }]
      let("X-Osuny-Token") { university_apps(:default_app).token }

      parameter name: :website_id, in: :path, type: :string, description: 'Website identifier'
      let(:website_id) { communication_websites(:website_with_github).id }

      response '200', 'Successful operation' do
        run_test!
      end

      response '401', 'Unauthorized. Please make sure you provide a valid API key.' do
        let("X-Osuny-Token") { 'fake-token' }
        run_test!
      end

      response '404', 'Website not found' do
        let(:website_id) { 'fake-id' }
        run_test!
      end
    end
  end
end

Les tests sont utilisés pour générer des fichiers openapi.json, par exemple sur https://demo.osuny.org/api/docs/osuny/v1/openapi.json, avec la commande suivante.

bash

RSWAG_DRY_RUN=0 rake rswag:specs:swaggerize

Pour générer la spécification OpenAPI en évitant les tests, il suffit d’omettre la variable d’environnement RSWAG_DRY_RUN. Cela permet d’avoir un aperçu rapide dans Swagger sans les exemples de réponse.

bash

rake rswag:specs:swaggerize

Utilisation de l’API Osuny

LHÉO