Hur man genererar ett Swagger Docs For Rails API

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

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.

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)

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

param_list :form, :payment_type, :string, :required, 'payment type', [: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 rake swagger: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) # Gör en skillnad mellan API:er och API-dokumentationsvägar. "apidocs/#{path}" slutet

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):

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

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