Creazione di un backend API - PARTE 1 -

Preparazione dell’ambiente di lavoro

Nella vostra cartella di lavoro , creiamo una nuova cartella per il progetto di esempio:

    $ mkdir myapi && cd myapi

Se avete più versioni di ruby installate sul vostro sistema sarebbe meglio creare il file .ruby-version in cui specificare la versione di ruby

    $ vi .ruby-version 
    # dentro il file inseriamo la versione , nel mio caso 
    3.1.2
    # salviamo e usciamo dall'editor VI 

Adesso eseguiamo :

$ gem install rails 
$ gem install bundler 

Adesso creiamo il nostro progetto di esempio API:

$ rails new . --api 
# con questo comando verrà generato la base di progetto con database predefinito sqlite3 
# ma se volete personalizzare il database basta aggiungere l'opzione --database=postgresql

Adesso per semplicità proviamo la creazione di un model:

$ rails g scaffold Post title:string body:text 
# eh si e il classico esempio ;) 

$ rails db:migrate

Adesso dovreste avare nel routes una cosa del genere:

Rails.application.routes.draw do
    resources :posts
    # Define your application routes per the DSL in https://guides.rubyonrails.org/routing.html

    # Defines the root path route ("/")
    # root "articles#index"
end

Non modifichiamo niente, ma adesso aggiungiamo SWAGGER per testare e documentare le nostre API:

Apriamo il Gemfile e aggiungiamo queste gemme:

group :development do
    gem 'rspec-rails'
    # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
    # gem "spring"
    gem 'factory_girl_rails'
    gem 'capybara'
    gem 'database_cleaner'
end

gem 'rswag'

Salvate il Gemfile ed eseguiamo :

$ bundle install

Adesso eseguiamo la configurazione di RSPEC:

$ rails generate rspec:install

PS: le gemme capybara, database_cleaner, factory_girl_rails non le configuriamo ma ve le lasciamo perchè normalmente vengono installate quando si vuole usare RSPEC per il TDD. Maggiori info

Installazione SWAGGER

Swagger è un tool per testare e documentare le vostre API, si può usare sia in ambiente d sviluppo che di produzione ma con alcuni accorgimenti che per ora non tratteremo. Per maggiori info vi rimandiamo alla doc ufficiale Swagger info.

$ rails g rswag:install

Adesso eseguiamo la creazione di rspec per swagger per eseguire i test:

$ rails g rspec:swagger API::V1::PostsController

Questo comando va formattato a seconda del controller che deve essere testato, in questo caso PostsController La versione di API è V1 ma potrebbe cambiare quando si vogliono avere più versioni di API disponibili.

Adesso eseguo il comando:

$ rails rswag:specs:swaggerize

che genera il file :

/swagger/v1/swagger.yaml

Questo file serve per la configurazione di swagger. Vediamo nel mio caso:

---
openapi: 3.0.1
info:
title: API V1
version: v1
paths:
"/posts":
    post:
    summary: Create an Post
    tags:
    - posts
    parameters: []
    responses:
        '201':
        description: post created
        '422':
        description: invalid request
    requestBody:
        content:
        application/json:
            schema:
            type: object
            properties:
                title:
                type: string
                body:
                type: text
            required:
            - title
            - body
servers:
- url: http://{defaultHost}
variables:
    defaultHost:
    default: localhost:3000

ATTEZIONE: Nel nostro caso avendo solo un controller PostsController vedrete solo il path: /posts

Inoltre notate la modifica del url e del default :

url: http://{defaultHost}

default: localhost:3000

Viene creato il file rspec nel seguente path:

spec/requests/api/v1/[nome-controller]_spec.rb

Nel nostro caso : spec/requests/api/v1/posts_spec.rb

Il file si presenta come segue dopo alcune modifiche:

require 'swagger_helper'

RSpec.describe 'posts_controller', type: :request do
    path "/posts" do
        post "Create an Post" do
        tags "posts"
        consumes "application/json"
        parameter name: :title, in: :body, schema: {
            type: :object,
            properties: {
            title: { type: :string },
            body: { type: :string },
            },
            required: ["title", "body"],
        }
    response "201", "post created" do
            let(:post) { { title: "Primo", body: "Body test 1" } }
            run_test!
        end
    response "422", "invalid request" do
            let(:post) { { title: "Secondo" } }
            run_test!
        end
        end
    end
end

Alcune note

Aprite il file /spec/swagger_spec.rb e potete modificare il parametro defaultHost come segue:

defaultHost: {
    default: 'localhost:3000'
}

Conclusione

Adesso avviamo il server rails:

$ bundle exec rails server

Apriamo l’ URL: http://localhost:3000/api-docs/index.html

e dovreste vedere la vostra interfaccia swagger e la possibilità di testare le vostre API

Per completezza se riaprite il file routes.rb dovreste avere una cosa del genere:

Rails.application.routes.draw do
    mount Rswag::Ui::Engine => '/api-docs'
    mount Rswag::Api::Engine => '/api-docs'
    resources :posts
    # Define your application routes per the DSL in https://guides.rubyonrails.org/routing.html

    # Defines the root path route ("/")
    # root "articles#index"
end

Tools Extra

Postman: Piattaforma per usare/testare tutto il lifecycle delle API. Vedi la guida ufficiale Postman