So richten Sie Swagger UI für ein Rails-Projekt ein

Klare, interaktive API-Dokumentation zu erstellen, ist ein wesentlicher Bestandteil der Entwicklung eines wartbaren und zugänglichen Webdienstes. Swagger UI dient als dynamische Dokumentationsschnittstelle für Entwickler, und die Integration in Ihr Ruby on Rails-Projekt kann das Entwicklererlebnis erheblich verbessern. In diesem Beitrag erläutern wir den Prozess der Einrichtung von Swagger UI mit zwei beliebten Gems, grape-swagger für Grape-APIs und rswag für RSpec-API-Dokumentation.

Teil 1: Für Grape-APIs

Grape ist ein REST-ähnliches API-Mikro-Framework für Ruby, das darauf ausgelegt ist, auf Rack zu laufen oder ein bestehendes Webanwendungs-Framework wie Rails zu ergänzen. Grape-swagger bietet eine automatisch generierte Dokumentation für Ihre Grape-API.

Schritt 1: Installation von `grape-swagger`

Fügen Sie grape-swagger zu Ihrer Gemfile hinzu und führen Sie bundle install aus, um es zu Ihrem Projekt hinzuzufügen:

gem 'grape-swagger'

Und dann ausführen:

bundle install

Schritt 2: Konfiguration von `grape-swagger`

Richten Sie einen Initialisierer für grape-swagger ein:

# config/initializers/swagger.rb

if defined?(Grape)
  GrapeSwaggerRails.options.url      = "/api/swagger_doc"
  GrapeSwaggerRails.options.app_name = "MyApp"
  GrapeSwaggerRails.options.app_url  = "/"
end

Schritt 3: Definieren von API-Entitäten und Dokumentation

Sie müssen Ihre API-Entitäten definieren, damit grape-swagger sie dokumentieren kann:

# app/api/entities/my_entity.rb

module API
  module Entities
    class MyEntity < Grape::Entity
      expose :id, documentation: { type: 'Integer', desc: 'ID of the entity' }
      # ... further code ...
    end
  end
end

Schritt 4: Hinzufügen von Swagger-Endpunkten

Fügen Sie in Ihrer API-Basisklasse die Swagger-Dokumentationsroute hinzu, damit sie das Swagger-JSON bereitstellen kann:

# app/api/base.rb

class API::Base < Grape::API
  add_swagger_documentation
end

Schritt 5: Anzeigen Ihrer Swagger-Dokumentation

Sie können nun auf Ihre Swagger UI zugreifen, indem Sie zu http://localhost:3000/swagger navigieren.

Teil 2: Für Rails-App mit RSpec

rswag integriert sich mit RSpec, um automatisch Swagger-kompatible API-Dokumentationen basierend auf Ihren API-Tests zu generieren.

Schritt 1: Installation von `rswag-specs`

Fügen Sie rswag-specs zu Ihrer Gemfile hinzu und installieren Sie es:

gem 'rswag-specs'

Und führen Sie dann aus:

bundle install

Schritt 2: Generierung von Konfiguration und Dateien

Führen Sie den RSwag-Generator aus, um die anfängliche Konfiguration und Verzeichnisse für Ihre API-Spezifikationen zu erstellen:

rails g rswag:install

Schritt 3: Schreiben von Anforderungsspezifikationen mit Swagger DSL

Erstellen Sie eine Spezifikationsdatei und verwenden Sie das DSL von RSwag, um sowohl Ihre Endpunkte zu testen als auch zu dokumentieren:

# spec/integration/my_api_spec.rb

require 'swagger_helper'

describe 'My API' do
  path '/my_api/endpoint' do
    ...
    get 'Retrieves something' do
      produces 'application/json'
      response '200', 'successful' do
        schema type: :object,
               properties: {
                 id: { type: :integer }
               },
               required: ['id']

        # Your test code goes here
      end
    end
  end
end

Schritt 4: Zugriff auf Ihre API-Dokumentation mit RSwag UI

RSwag bietet eine Swagger UI, auf die Sie unter http://localhost:3000/api-docs zugreifen können. Diese UI spiegelt direkt die von Ihnen geschriebenen Spezifikationen wider.

Alternative

Wenn Sie kein RSpec schreiben möchten oder GrapeAPI nicht verwenden, können Sie unser neuestes Automatisierungstool ausprobieren: Cordyline.

Automatisch Swagger-Dokumentation generieren

Mit nur einem Drag & Drop generieren wir die gesamte Swagger-Dokumentation für Sie, ohne eine einzige Zeile Code.