Come generare un'API Swagger Docs For Rails

Making API for a Rails application is simple for a Ruby on Rails developer. In any case, how different clients/customers will know whether the API is working fine or not without a customer side application. Is there any answer for this which I can report for API inside the Rails application, The answer is yes we have numerous instruments and methodologies however I would favor swagger UI.

In this article I am going to disclose how to make Rails API documentation using swagger UI.

Prerequisites:-
I am going to use one sample posts application which serves API calls.

Gem:-
To Integrate swagger UI for Rails API I am using a gem called swagger-docs. Add this gem to your Gemfile in your application and do bundle install.

Swagger initializer file:-
After bundling the gem create an initializer in config/initializers(e.g. swagger.rb) and specify the following options:

#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" => "" } } } })

Refer below url for the list of configarations
https://github.com/richhollis/swagger-docs#configuration-options

swagger_controller and swagger_API are helpers to provide swagger UI documentation.

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)

To handle enums:-
Pass list of enum values.
Ex:-

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

Generating json files:-

rake swagger:docs (Errors are not displayed by default with this command)

To see all error messages use the command below:

SD_LOG_LEVEL=1 spavalderia:docs

Swagger UI integration

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

Before that please add below code to swagger.rb to
make a distinction between the APIs and API documentation paths.

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

Create apidocs directory under public and api directory under apidocs.

Copy downloaded swagger-ui to the public/apidocs/api and index.html to public/apidocs.

Edit index.html
Change swagger url in window.swaggerUi function to url: “/apidocs/api-docs.json”.
It should be pointed to api-docs.json file under public/apidocs.
Because, it will generate under that path as per the configation we defined in swagger.rb

Now we all are set. IF you are running the the server stop and restart the rails server. Go to browser and try to access “http://localhost:3000/apidocs/index”. You can click on available links(show/hide, List operations, Expand Operations and Raw) on each resource(posts etc):

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

Also read  :  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!