Wie man eine Swagger-Dokumentation für Rails-API generiert

Die Erstellung einer API für eine Rails-Anwendung ist für einen Ruby on Rails-Entwickler einfach. In jedem Fall, wie verschiedene Kunden / Kunden wissen, ob die API funktioniert oder nicht, ohne eine kundenseitige Anwendung. Gibt es irgendeine Antwort für diese, die ich für API innerhalb der Rails-Anwendung berichten kann? Die Antwort ist ja, wir haben zahlreiche Instrumente und Methoden, aber ich würde Swagger UI bevorzugen.

In diesem Artikel werde ich zeigen, wie man Rails API-Dokumentation mit Swagger UI erstellt.

Voraussetzungen:-
Ich werde eine Beispielanwendung für Posts verwenden, die API-Aufrufe bedient.

Edelstein:-
Um Swagger UI für Rails API zu integrieren, verwende ich ein Gem namens swagger-docs. Fügen Sie dieses Gem zu Ihrem Gemfile in Ihrer Anwendung hinzu und führen Sie eine Bundle-Installation durch.

Swagger-Initialisierungsdatei:-
Nach dem Bündeln des Edelsteins erstellen Sie einen Initializer in config/initializers (z.B. swagger.rb) und geben Sie die folgenden Optionen an:

#File config/initializers/swagger.rb
  Swagger::Docs::Config.register_apis({
  "1.0" => {
    # die für die API verwendete Erweiterung
    :api_extension_type => :json,
    # der Ausgabeort, an den die .json-Dateien geschrieben werden
    :api_file_path => "public/apidocs",
    # der URL-Basispfad zu Ihrer API
    :base_path => "http://localhost:3000",
    # wenn Sie alle .json-Dateien bei jeder Generierung löschen wollen
    :clean_directory => true,
    # fügen Sie benutzerdefinierte Attribute zu api-docs hinzu
    :attributes => {
      :info => {
        "title" =>; "Ihr Anwendungstitel",
        "description" =>; "Rails API-Dokumentation mit Swagger UI.",
        "termsOfServiceUrl" => "",
        "contact" => ""
       }
     }
  }
})

Die Liste der Konfigurationen finden Sie unter folgender URL
https://github.com/richhollis/swagger-docs#configuration-options

swagger_controller und swagger_API sind Hilfsmittel zur Bereitstellung der Swagger-UI-Dokumentation.

Modul Api

Baustein V1

  Klasse PostsController < AnwendungsController

         respond_to :json
         swagger_controller :posts, 'Beitrags-Controller'
         swagger_api :create do
               summary 'Beiträge erstellen'
               notes 'Sollte zum Erstellen von Beiträgen verwendet werden'
               param :form, 'post[name]', :string, :required, 'name'
               param :form, 'post[publish]', :boolean, :required, 'publish'
          end
          swagger_api :index do
                summary 'Alle Beiträge abrufen'
                notes 'Sollte für das Abrufen aller Beiträge verwendet werden'
                param :header, :Authoraization, :string, :required, 'Authoraization'
                antwort :unauthorized
                antwort :ok, "Erfolg"
          end
          swagger_api :show do
                summary 'Alle Beiträge abrufen'
                notes 'Sollte zum Abrufen eines Beitrags verwendet werden'
                param :path, :id, :string, :id
                antwort :unautorisiert
                antwort :ok, "Erfolg"
           end
           swagger_api :destroy do
                 summary 'Zerstöre den Beitrag'
                 notes 'Sollte zum Zerstören eines Beitrags verwendet werden'
                 param :path, :id, :string, :id
                 antwort :unautorisiert
                 antwort :ok, "Erfolg"
            end
       end
   end
end

Bsp:-

param :header, :Authoraization, :string, :required, 'Zur Autorisierung der Anfragen.'
param :path, :id, :integer, :required, 'Beitragsnummer, die den Datensatz abrufen soll'
param :form, :name, :string, :optional, 'Name des Beitrags'
param :query, :query_name, :string, :optional, 'Abfragename'

param - Standard-API-Parameter

 erster Wert: parameter_type(Typen: form, path, header, query)
zweiter Wert: Name des Parameters
 dritter Wert: Datentyp des Parameters
 vierter Wert: erforderlich/optional
 fünfter Wert: Kleine Beschreibung des Parameters
 sechster Wert: Liste von Werten in eckigen Klammern, um Enums zu handhaben (optional)

Zur Handhabung von Enums:-
Übergeben Sie eine Liste von Enum-Werten.
Bsp:-

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

Erzeugen von json-Dateien:-

rake swagger:docs (Fehler werden bei diesem Befehl standardmäßig nicht angezeigt)

Um alle Fehlermeldungen anzuzeigen, verwenden Sie den folgenden Befehl:

SD_LOG_LEVEL=1 rake swagger:docs

Swagger UI-Integration

Bitte laden Sie Swagger UI herunter.
https://github.com/richhollis/swagger-docs-sample/tree/master/public/api

Vorher fügen Sie bitte den folgenden Code in swagger.rb ein, um
zwischen den Pfaden der APIs und der API-Dokumentation unterscheiden.

Klasse Swagger::Docs::Config
  def self.transform_path(path, api_version)
    # Unterscheiden Sie zwischen den Pfaden der APIs und der API-Dokumentation.
    "apidocs/#{Pfad}"
  end
end

Erstellen Sie das Verzeichnis apidocs unter public und das Verzeichnis api unter apidocs.

Kopieren Sie das heruntergeladene swagger-ui in das Verzeichnis public/apidocs/api und index.html in public/apidocs.

index.html bearbeiten
Ändern Sie die Swagger-Url in der Funktion window.swaggerUi in url: "/apidocs/api-docs.json".
Es sollte auf die Datei api-docs.json unter public/apidocs verwiesen werden.
Denn es wird unter diesem Pfad gemäß der in swagger.rb definierten Konfigation generiert

Jetzt sind wir alle bereit. WENN Sie den Server laufen lassen, stoppen Sie den Rails-Server und starten Sie ihn neu. Gehen Sie zum Browser und versuchen Sie, auf „http://localhost:3000/apidocs/indexâ€â€œ zuzugreifen. Sie können auf die verfügbaren Links (anzeigen/ausblenden, Operationen auflisten, Operationen erweitern und Raw) auf jeder Ressource (Beiträge usw.) klicken:

Lesen Sie auch: Verfolgen Sie Änderungen an den Daten Ihres Modells mit Paper Trail Gem

Lesen Sie auch :  Mandantenfähige Architektur mit PostgreSQL-Schemata

Möchten Sie mehr über unsere Fähigkeiten in der Rails-Entwicklung und unsere bisherigen Projekte erfahren? In Kontakt kommen jetzt mit uns!