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 'Post API' do
  path '/communication/websites/:website_id/posts' do
    get 'List the posts in a website' do
      tags 'Communication::Website::Post'
      consumes 'application/json'

      parameter name: :website_id,
                in: :path, 
                type: :string, 
                description: 'Website identifier',
                example: 'c8a4bed5-2e05-47e4-90e3-cf334c16453f'

      response '200', 'successful operation' do
        schema type: :object,
          properties: {
            id: { type: :string },
            title: { type: :string },
          },
          required: [ 'name', 'url' ]
        example 'application/json', :response, [
            {
              id: 'c8a4bed5-2e05-47e4-90e3-cf334c16453f',
              title: 'Référentiel général d\'écoconception de services numériques (RGESN)'
            }
          ]
        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

rake rswag:specs:swaggerize

Utilisation de l’API Osuny

LHÉO