{"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":"swagger-dokumente-generieren-rails-api","status":"publish","type":"post","link":"https:\/\/www.railscarma.com\/de\/blog\/fachartikel\/swagger-dokumente-generieren-rails-api\/","title":{"rendered":"Wie man eine Swagger-Dokumentation f\u00fcr Rails-API generiert"},"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

Die Erstellung einer API f\u00fcr eine Rails-Anwendung ist f\u00fcr 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\u00fcr diese, die ich f\u00fcr API innerhalb der Rails-Anwendung berichten kann? Die Antwort ist ja, wir haben zahlreiche Instrumente und Methoden, aber ich w\u00fcrde Swagger UI bevorzugen.<\/p>\n

In diesem Artikel werde ich zeigen, wie man Rails API-Dokumentation mit Swagger UI erstellt.<\/p>\n

Voraussetzungen:-
Ich werde eine Beispielanwendung f\u00fcr Posts verwenden, die API-Aufrufe bedient.<\/p>\n

Edelstein:-
Um Swagger UI f\u00fcr Rails API zu integrieren, verwende ich ein Gem namens swagger-docs. F\u00fcgen Sie dieses Gem zu Ihrem Gemfile in Ihrer Anwendung hinzu und f\u00fchren Sie eine Bundle-Installation durch.<\/p>\n

Swagger-Initialisierungsdatei:-
Nach dem B\u00fcndeln des Edelsteins erstellen Sie einen Initializer in config\/initializers (z.B. swagger.rb) und geben Sie die folgenden Optionen an:<\/p>\n

#File config\/initializers\/swagger.rb\n  Swagger::Docs::Config.register_apis({\n  \"1.0\" => {\n    # die f\u00fcr die API verwendete Erweiterung\n    :api_extension_type => :json,\n    # der Ausgabeort, an den die .json-Dateien geschrieben werden\n    :api_file_path => \"public\/apidocs\",\n    # der URL-Basispfad zu Ihrer API\n    :base_path => \"http:\/\/localhost:3000\",\n    # wenn Sie alle .json-Dateien bei jeder Generierung l\u00f6schen wollen\n    :clean_directory => true,\n    # f\u00fcgen Sie benutzerdefinierte Attribute zu api-docs hinzu\n    :attributes => {\n      :info => {\n        \"title\" =>; \"Ihr Anwendungstitel\",\n        \"description\" =>; \"Rails API-Dokumentation mit Swagger UI.\",\n        \"termsOfServiceUrl\" => \"\",\n        \"contact\" => \"\"\n       }\n     }\n  }\n})\n<\/code><\/pre>\n
Die Liste der Konfigurationen finden Sie unter folgender URL
https:\/\/github.com\/richhollis\/swagger-docs#configuration-options<\/p>\n
swagger_controller und swagger_API sind Hilfsmittel zur Bereitstellung der Swagger-UI-Dokumentation.<\/p>\n
\nModul Api\n\nBaustein V1\n\n  Klasse PostsController < AnwendungsController\n\n         respond_to :json\n         swagger_controller :posts, 'Beitrags-Controller'\n         swagger_api :create do\n               summary 'Beitr\u00e4ge erstellen'\n               notes 'Sollte zum Erstellen von Beitr\u00e4gen verwendet werden'\n               param :form, 'post[name]', :string, :required, 'name'\n               param :form, 'post[publish]', :boolean, :required, 'publish'\n          end\n          swagger_api :index do\n                summary 'Alle Beitr\u00e4ge abrufen'\n                notes 'Sollte f\u00fcr das Abrufen aller Beitr\u00e4ge verwendet werden'\n                param :header, :Authoraization, :string, :required, 'Authoraization'\n                antwort :unauthorized\n                antwort :ok, "Erfolg"\n          end\n          swagger_api :show do\n                summary 'Alle Beitr\u00e4ge abrufen'\n                notes 'Sollte zum Abrufen eines Beitrags verwendet werden'\n                param :path, :id, :string, :id\n                antwort :unautorisiert\n                antwort :ok, "Erfolg"\n           end\n           swagger_api :destroy do\n                 summary 'Zerst\u00f6re den Beitrag'\n                 notes 'Sollte zum Zerst\u00f6ren eines Beitrags verwendet werden'\n                 param :path, :id, :string, :id\n                 antwort :unautorisiert\n                 antwort :ok, "Erfolg"\n            end\n       end\n   end\nend\n<\/code><\/pre>\n
Bsp:-<\/p>\n
param :header, :Authoraization, :string, :required, 'Zur Autorisierung der Anfragen.'\nparam :path, :id, :integer, :required, 'Beitragsnummer, die den Datensatz abrufen soll'\nparam :form, :name, :string, :optional, 'Name des Beitrags'\nparam :query, :query_name, :string, :optional, 'Abfragename'<\/code><\/pre>\n
param - Standard-API-Parameter<\/p>\n
 erster Wert: parameter_type(Typen: form, path, header, query)\nzweiter Wert: Name des Parameters\n dritter Wert: Datentyp des Parameters\n vierter Wert: erforderlich\/optional\n f\u00fcnfter Wert: Kleine Beschreibung des Parameters\n sechster Wert: Liste von Werten in eckigen Klammern, um Enums zu handhaben (optional)<\/code><\/pre>\n
Zur Handhabung von Enums:-
\u00dcbergeben Sie eine Liste von Enum-Werten.
Bsp:-<\/p>\n
param_list :form, :payment_type, :string, :required, 'payment type',\n[:check, :cash, :wire_transfer, :demand_draft]<\/code><\/pre>\n
Erzeugen von json-Dateien:-<\/p>\n
rake swagger:docs (Fehler werden bei diesem Befehl standardm\u00e4\u00dfig nicht angezeigt)<\/p>\n
Um alle Fehlermeldungen anzuzeigen, verwenden Sie den folgenden Befehl:<\/p>\n
SD_LOG_LEVEL=1 rake swagger:docs<\/code><\/pre>\n
Swagger UI-Integration<\/p>\n
Bitte laden Sie Swagger UI herunter.
https:\/\/github.com\/richhollis\/swagger-docs-sample\/tree\/master\/public\/api<\/a><\/p>\n
Vorher f\u00fcgen Sie bitte den folgenden Code in swagger.rb ein, um
zwischen den Pfaden der APIs und der API-Dokumentation unterscheiden.<\/p>\n
Klasse Swagger::Docs::Config\n  def self.transform_path(path, api_version)\n    # Unterscheiden Sie zwischen den Pfaden der APIs und der API-Dokumentation.\n    \"apidocs\/#{Pfad}\"\n  end\nend<\/code><\/pre>\n
Erstellen Sie das Verzeichnis apidocs unter public und das Verzeichnis api unter apidocs.<\/p>\n
Kopieren Sie das heruntergeladene swagger-ui in das Verzeichnis public\/apidocs\/api und index.html in public\/apidocs.<\/p>\n
index.html bearbeiten
\u00c4ndern 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\u00e4\u00df der in swagger.rb definierten Konfigation generiert<\/p>\n
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 \u00e2\u20ac\u017ehttp:\/\/localhost:3000\/apidocs\/index\u00e2\u20ac\u00e2\u20ac\u0153 zuzugreifen. Sie k\u00f6nnen auf die verf\u00fcgbaren Links (anzeigen\/ausblenden, Operationen auflisten, Operationen erweitern und Raw) auf jeder Ressource (Beitr\u00e4ge usw.) klicken:<\/p>\n
\"swagger-doc-1\"<\/a> \"swagger-doc-2\"<\/a><\/p>\n
Lesen Sie auch: Verfolgen Sie \u00c4nderungen an den Daten Ihres Modells mit Paper Trail Gem<\/a><\/p>\n
Lesen Sie auch :  Mandantenf\u00e4hige Architektur mit PostgreSQL-Schemata<\/a><\/p>\n
M\u00f6chten Sie mehr \u00fcber unsere F\u00e4higkeiten in der Rails-Entwicklung und unsere bisherigen Projekte erfahren? In Kontakt kommen<\/a> jetzt mit uns!  <\/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
Abonnieren Sie die neuesten Updates<\/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