Hur man genererar ett Swagger Docs For Rails API

Att skapa API för en Rails-applikation är enkelt för en Ruby on Rails-utvecklare. Hur som helst, hur olika kunder / kunder kommer att veta om API fungerar bra eller inte utan en applikation på kundsidan. Finns det något svar på detta som jag kan rapportera för API inuti Rails-applikationen, svaret är ja vi har många instrument och metoder men jag skulle föredra swagger UI.

I den här artikeln kommer jag att avslöja hur man gör Rails API-dokumentation med hjälp av swagger UI.

Förkunskapskrav: -
Jag kommer att använda en exempelpostapplikation som tjänar API-anrop.

Gem: -
För att integrera swagger UI för Rails API använder jag en pärla som heter swagger-docs. Lägg till den här pärlan i din Gemfile i din applikation och gör bundle-installation.

Swagger-initialiseringsfil: -
När du har buntat ihop pärlan skapar du en initialiserare i config/initializers (t.ex. swagger.rb) och anger följande alternativ:

#File config/initializers/swagger.rb Swagger::Docs::Config.register_apis({ "1.0" => { # tillägget som används för API:et :api_extension_type => :json, # utdataplatsen där dina .json-filer skrivs till :api_file_path => "public/apidocs", # URL-bassökvägen till ditt API :base_path => "http://localhost:3000", # om du vill ta bort alla .json-filer vid varje generation :clean_directory => true, # lägg till anpassade attribut till api-docs :attributes => { :info => { "title" =>; "Din applikationstitel", "description" =>; "Rails API-dokumentation med Swagger UI.", "termsOfServiceUrl". " => "", "kontakt" => "" } } } })

Se nedanstående webbadress för en lista över konfigurationer
https://github.com/richhollis/swagger-docs#configuration-options

swagger_controller och swagger_API är hjälpmedel för att tillhandahålla dokumentation av swaggergränssnittet.

modul Api-modul V1 klass PostsController < ApplicationController respond_to :json swagger_controller :posts, 'Post Controller' swagger_api :create gör sammanfattning 'Skapa inlägg'-anteckningar 'Bör användas för att skapa inlägg' param :form, 'post[name]', :string , :required, 'name' param :form, 'post[publish]', :boolean, :required, 'publish' end swagger_api :index do summary 'Hämta alla inlägg' anteckningar 'Bör användas för att hämta alla inlägg' param :header, :Auktorisation, :string, :required, 'Authorization'-svar :obehörigt svar :ok, "Framgång" end swagger_api :show gör sammanfattning 'Hämta alla inlägg' anteckningar 'Bör användas för att hämta ett inlägg' param :path , :id, :string, :id-svar :obehörigt svar :ok, "Framgång" end swagger_api :destroy gör sammanfattning 'Förstör inlägget'-anteckningar 'Bör användas för att förstöra ett inlägg' param :sökväg, :id, :sträng, :id-svar :otillåtet svar :ok, "Framgång" slut slut slut slut

Ex:-

param :header, :Authorization, :string, :required, 'För att auktorisera förfrågningarna.' param :sökväg, :id, :integer, :required, 'post-id som ska hämta posten' param :form, :name, :string, :valfritt, 'namn på inlägget' param :query, :query_name, : sträng, :valfritt, 'frågans namn'

param – Standard API-parameter

 första värdet: parameter_type(typer: form, sökväg, rubrik, fråga) andra värdet: namnet på parametern tredje värdet: datatyp för parametern fjärde värde: obligatoriskt/valfritt femte värdet: Liten beskrivning av parametern sjätte värdet: lista över värden i fyrkantiga fästen för att hantera enums (valfritt)

För att hantera enumer:-
Skicka en lista med enumvärden.
Ex:-

param_list :form, :payment_type, :string, :required, 'payment type', [:check, :cash, :wire_transfer, :demand_draft]

Generering av json-filer

rake swagger:docs (Fel visas inte som standard med detta kommando)

Om du vill se alla felmeddelanden använder du kommandot nedan:

SD_LOG_LEVEL=1 rake swagger:docs

Swagger UI-integration

Vänligen ladda ner swagger ui.
https://github.com/richhollis/swagger-docs-sample/tree/master/public/api

Innan du gör det, lägg till nedanstående kod i swagger.rb för att
göra en åtskillnad mellan API:er och API-dokumentationssökvägar.

class Swagger::Docs::Config def self.transform_path(path, api_version) # Gör en skillnad mellan API:er och API-dokumentationsvägar. "apidocs/#{path}" slutet

Skapa katalogen apidocs under public och katalogen api under apidocs.

Kopiera nedladdad swagger-ui till public/apidocs/api och index.html till public/apidocs.

Redigera index.html
Ändra swagger url i window.swaggerUi funktionen till url: “/apidocs/api-docs.json”.
Den ska peka på filen api-docs.json under public/apidocs.
Eftersom det kommer att genereras under den sökvägen enligt den konfiguration som vi definierade i swagger.rb

Nu är vi alla redo. OM du kör servern, stoppa och starta om rails-servern. Gå till webbläsaren och försök att komma åt "http://localhost:3000/apidocs/indexâ€. Du kan klicka på tillgängliga länkar (visa / dölja, lista operationer, expandera operationer och rå) på varje resurs (inlägg etc.):

Läs även: Spåra ändringar i din modells data med Paper Trail Gem

Läs också :  Arkitektur för flera hyresgäster med PostgreSQL-scheman

Vill du lära dig mer om våra Rails-utvecklingsfärdigheter och tidigare projekt? Komma i kontakt med oss nu!