{"id":8856,"date":"2016-09-23T11:21:15","date_gmt":"2016-09-23T11:21:15","guid":{"rendered":"https:\/\/dev.railscarma.com\/generate-swagger-docs-rails-api\/"},"modified":"2024-01-10T13:06:39","modified_gmt":"2024-01-10T13:06:39","slug":"generare-api-per-guide-di-documenti-spavaldi","status":"publish","type":"post","link":"https:\/\/www.railscarma.com\/it\/blog\/articoli-tecnici\/generare-api-per-guide-di-documenti-spavaldi\/","title":{"rendered":"Come generare un'API Swagger Docs For Rails"},"content":{"rendered":"
\n\t\t\t\t\t\t
\n\t\t\t\t\t\t
\n\t\t\t\t\t
\n\t\t\t
\n\t\t\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

Creare API per un'applicazione Rails \u00e8 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'\u00e8 una risposta a questo problema che posso segnalare per le API all'interno dell'applicazione Rails? La risposta \u00e8 s\u00ec, abbiamo numerosi strumenti e metodologie, ma preferirei l'interfaccia utente swagger.<\/p>\n

In questo articolo spiegher\u00f2 come realizzare la documentazione delle API di Rails utilizzando l'interfaccia swagger.<\/p>\n

Prerequisiti:-
Utilizzer\u00f2 un'applicazione di esempio per i post che serve le chiamate API.<\/p>\n

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.<\/p>\n

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

#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" => "" } } } })\n<\/code><\/pre>\n
Fare riferimento all'url sottostante per l'elenco delle configurazioni
https:\/\/github.com\/richhollis\/swagger-docs#configuration-options<\/p>\n
swagger_controller e swagger_API sono helper per fornire la documentazione dell'interfaccia utente di swagger.<\/p>\n
\nmodulo 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\n<\/code><\/pre>\n
Ex:-<\/p>\n
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'<\/code><\/pre>\n
param: parametro API standard<\/p>\n
 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)<\/code><\/pre>\n
Per gestire gli enum
Passare un elenco di valori enum.
Ex:-<\/p>\n
param_list :form, :payment_type, :string, :required, 'tipo di pagamento', [:check, :cash, :wire_transfer, :demand_draft]<\/code><\/pre>\n
Generazione di file json<\/p>\n
rake swagger:docs (gli errori non vengono visualizzati per impostazione predefinita con questo comando)<\/p>\n
Per visualizzare tutti i messaggi di errore, utilizzare il comando seguente:<\/p>\n
SD_LOG_LEVEL=1 spavalderia:docs<\/code><\/pre>\n
Integrazione dell'interfaccia utente Swagger<\/p>\n
Scaricare swagger ui.
https:\/\/github.com\/richhollis\/swagger-docs-sample\/tree\/master\/public\/api<\/a><\/p>\n
Prima di ci\u00f2, aggiungere il codice seguente a swagger.rb per
fare una distinzione tra i percorsi delle API e della documentazione delle API.<\/p>\n
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<\/code><\/pre>\n
Creare la cartella apidocs sotto public e la cartella api sotto apidocs.<\/p>\n
Copiare swagger-ui scaricato in public\/apidocs\/api e index.html in public\/apidocs.<\/p>\n
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\u00e9 verr\u00e0 generato sotto quel percorso, secondo la configurazione definita in swagger.rb<\/p>\n
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\u00e2\u20ac. \u00c8 possibile fare clic sui collegamenti disponibili (mostra\/nascondi, Elenco operazioni, Espandi operazioni e Raw) su ogni risorsa (post ecc.):<\/p>\n
\"spavalderia-doc-1\"<\/a> \"spavalderia-doc-2\"<\/a><\/p>\n
Leggi anche: Tieni traccia delle modifiche ai dati del tuo modello con Paper Trail Gem<\/a><\/p>\n
Leggi anche :  Architettura multi-tenant con schemi PostgreSQL<\/a><\/p>\n
Vuoi saperne di pi\u00f9 sulle nostre capacit\u00e0 di sviluppo di Rails e sui progetti passati? Mettiti in contatto<\/a> con noi adesso!  <\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t<\/section>\n\t\t\t\t
\n\t\t\t\t\t\t
\n\t\t\t\t\t
\n\t\t\t
\n\t\t\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t
Iscriviti per gli ultimi aggiornamenti<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t
\t\t\t\t\t