Come generare un'API Swagger Docs For Rails

Creare API per un'applicazione Rails è semplice per uno sviluppatore Ruby on Rails. In ogni caso, come fanno i diversi clienti a sapere se l'API funziona bene o no senza un'applicazione lato cliente? C'è una risposta a questo problema che posso segnalare per le API all'interno dell'applicazione Rails? La risposta è sì, abbiamo numerosi strumenti e metodologie, ma preferirei l'interfaccia utente swagger.

In questo articolo spiegherò come realizzare la documentazione delle API di Rails utilizzando l'interfaccia swagger.

Prerequisiti:-
Utilizzerò un'applicazione di esempio per i post che serve le chiamate API.

Gemma:-
Per integrare l'interfaccia swagger per le API di Rails, sto usando una gemma chiamata swagger-docs. Aggiungete questo gemma al vostro Gemfile nell'applicazione e fate l'installazione del bundle.

File inizializzatore di Swagger:-
Dopo il bundle della gemma, creare un inizializzatore in config/initializers (ad esempio swagger.rb) e specificare le seguenti opzioni:

#File config/initializers/swagger.rb Swagger::Docs::Config.register_apis({ "1.0" => { # l'estensione utilizzata per l'API :api_extension_type => :json, # il percorso di output in cui vengono scritti i file .json a :api_file_path => "public/apidocs", # il percorso base dell'URL della tua API :base_path => "http://localhost:3000", # se desideri eliminare tutti i file .json ad ogni generazione :clean_directory => true, # aggiunge attributi personalizzati a api-docs :attributes => { :info => { "title" =>; "Titolo dell'applicazione", "description" =>; "Documentazione API Rails con interfaccia utente Swagger.", "termsOfServiceUrl " => "", "contatto" => "" } } } })

Fare riferimento all'url sottostante per l'elenco delle configurazioni
https://github.com/richhollis/swagger-docs#configuration-options

swagger_controller e swagger_API sono helper per fornire la documentazione dell'interfaccia utente di swagger.

modulo Api modulo V1 classe PostController < ApplicationController rispondi_to :json swagger_controller :posts, 'Post Controller' swagger_api :crea do summary 'Creazione di post' note 'Dovrebbe essere utilizzato per creare post' param :form, 'post[nome]', :string , :required, 'name' param :form, 'post[pubblica]', :boolean, :required, 'pubblica' end swagger_api :index do summary 'Ricevi tutti i post' note 'Deve essere utilizzato per recuperare tutti i post' param :header, :Authoraization, :string, :required, 'Authoraization' risposta :risposta non autorizzata :ok, "Success" end swagger_api :mostra riepilogo 'Ricevi tutti i post' note 'Dovrebbe essere utilizzato per recuperare un post' param :path , :id, :string, :id risposta :risposta non autorizzata :ok, "Successo" end swagger_api :destroy do summary 'Distruggi il post' notes 'Dovrebbe essere utilizzato per distruggere un post' param :path, :id, :string, :id risposta :risposta non autorizzata :ok, "Successo" end end end end

Ex:-

param :header, :Authoraization, :string, :required, 'Per autorizzare le richieste.' param :percorso, :id, :intero, :required, 'id post che dovrebbe recuperare il record' param :form, :name, :string, :opzionale, 'nome del post' param :query, :query_name, : stringa, :opzionale, 'nome query'

param: parametro API standard

 primo valore: tipo_parametro(tipi: modulo, percorso, intestazione, query) secondo valore: nome del parametro terzo valore: tipo di dati del parametro quarto valore: obbligatorio/facoltativo quinto valore: breve descrizione del parametro sesto valore: elenco di valori in parentesi quadre per gestire le enumerazioni (opzionale)

Per gestire gli enum
Passare un elenco di valori enum.
Ex:-

param_list :form, :payment_type, :string, :required, 'tipo di pagamento', [:check, :cash, :wire_transfer, :demand_draft]

Generazione di file json

rake swagger:docs (gli errori non vengono visualizzati per impostazione predefinita con questo comando)

Per visualizzare tutti i messaggi di errore, utilizzare il comando seguente:

SD_LOG_LEVEL=1 spavalderia:docs

Integrazione dell'interfaccia utente Swagger

Scaricare swagger ui.
https://github.com/richhollis/swagger-docs-sample/tree/master/public/api

Prima di ciò, aggiungere il codice seguente a swagger.rb per
fare una distinzione tra i percorsi delle API e della documentazione delle API.

class Swagger::Docs::Config def self.transform_path(path, api_version) # Fare una distinzione tra le API e i percorsi della documentazione API. "apidocs/#{percorso}" fine fine

Creare la cartella apidocs sotto public e la cartella api sotto apidocs.

Copiare swagger-ui scaricato in public/apidocs/api e index.html in public/apidocs.

Modificare index.html
Cambiare l'url di swagger nella funzione window.swaggerUi in url: "/apidocs/api-docs.json".
Deve puntare al file api-docs.json sotto public/apidocs.
Perché verrà generato sotto quel percorso, secondo la configurazione definita in swagger.rb

Ora siamo tutti pronti. SE si sta eseguendo il server fermare e riavviare il server rails. Andare nel browser e provare ad accedere a http://localhost:3000/apidocs/indexâ€. È possibile fare clic sui collegamenti disponibili (mostra/nascondi, Elenco operazioni, Espandi operazioni e Raw) su ogni risorsa (post ecc.):

Leggi anche: Tieni traccia delle modifiche ai dati del tuo modello con Paper Trail Gem

Leggi anche :  Architettura multi-tenant con schemi PostgreSQL

Vuoi saperne di più sulle nostre capacità di sviluppo di Rails e sui progetti passati? Mettiti in contatto con noi adesso!