{"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":"generate-swagger-docs-rails-api","status":"publish","type":"post","link":"https:\/\/www.railscarma.com\/fr\/blog\/articles-techniques\/generate-swagger-docs-rails-api\/","title":{"rendered":"Comment g\u00e9n\u00e9rer une documentation Swagger pour une API Rails"},"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

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.<\/p>\n

In this article I am going to disclose how to make Rails API documentation using swagger UI.<\/p>\n

Prerequisites:-
I am going to use one sample posts application which serves API calls.<\/p>\n

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.<\/p>\n

Swagger initializer file:-
After bundling the gem create an initializer in config\/initializers(e.g. swagger.rb) and specify the following options:<\/p>\n

#File config\/initializers\/swagger.rb\n  Swagger::Docs::Config.register_apis({\n  \"1.0\" => {\n    # the extension used for the API\n    :api_extension_type => :json,\n    # the output location where your .json files are written to\n    :api_file_path => \"public\/apidocs\",\n    # the URL base path to your API\n    :base_path => \"http:\/\/localhost:3000\",\n    # if you want to delete all .json files at each generation\n    :clean_directory => true,\n    # add custom attributes to api-docs\n    :attributes => {\n      :info => {\n        \"title\" =>; \"Your application title\",\n        \"description\" =>; \"Rails API documention with Swagger UI.\",\n        \"termsOfServiceUrl\" => \"\",\n        \"contact\" => \"\"\n       }\n     }\n  }\n})\n<\/code><\/pre>\n
Refer below url for the list of configarations
https:\/\/github.com\/richhollis\/swagger-docs#configuration-options<\/p>\n
swagger_controller and swagger_API are helpers to provide swagger UI documentation.<\/p>\n
\nmodule Api\n\nmodule V1\n\n  class PostsController < ApplicationController\n\n         respond_to :json\n         swagger_controller :posts, 'Post Controller'\n         swagger_api :create do\n               summary 'Creating posts'\n               notes 'Should be used for creating posts'\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 'Get all the posts'\n                notes 'Should be used for fetching all posts'\n                param :header, :Authoraization, :string, :required, 'Authoraization'\n                response :unauthorized\n                response :ok, \"Success\"\n          end\n          swagger_api :show do\n                summary 'Get all the posts'\n                notes 'Should be used for fetching a post'\n                param :path, :id, :string, :id\n                response :unauthorized\n                response :ok, \"Success\"\n           end\n           swagger_api :destroy do\n                 summary 'Destroy the post'\n                 notes 'Should be used for destroying a post'\n                 param :path, :id, :string, :id\n                 response :unauthorized\n                 response :ok, \"Success\"\n            end\n       end\n   end\nend\n<\/code><\/pre>\n
Ex:-<\/p>\n
param :header, :Authoraization, :string, :required, 'To authorize the requests.'\nparam :path, :id, :integer, :required, 'post id that supposed to fetch the record'\nparam :form, :name, :string, :optional, 'name of the post'\nparam :query, :query_name, :string, :optional, 'query name'<\/code><\/pre>\n
param – Standard API parameter<\/p>\n
 first value: parameter_type(types: form, path, header, query)\nsecond value: name of the parameter\n third value: datatype of the parameter\n fouth value: required\/optional\n fifth value: Small description about the parameter\n sixth value: list of values in sqaure brackets to hanle enums(optional)<\/code><\/pre>\n
To handle enums:-
Pass list of enum values.
Ex:-<\/p>\n
param_list :form, :payment_type, :string, :required, 'payment type', \n[:check, :cash, :wire_transfer, :demand_draft]<\/code><\/pre>\n
Generating json files:-<\/p>\n
rake swagger:docs (Errors are not displayed by default with this command)<\/p>\n
To see all error messages use the command below:<\/p>\n
SD_LOG_LEVEL=1 rake swagger:docs<\/code><\/pre>\n
Swagger UI integration<\/p>\n
Please download swagger ui.
https:\/\/github.com\/richhollis\/swagger-docs-sample\/tree\/master\/public\/api<\/a><\/p>\n
Before that please add below code to swagger.rb to
make a distinction between the APIs and API documentation paths.<\/p>\n
class Swagger::Docs::Config\n  def self.transform_path(path, api_version)\n    # Make a distinction between the APIs and API documentation paths.\n    \"apidocs\/#{path}\"\n  end\nend<\/code><\/pre>\n
Create apidocs directory under public and api directory under apidocs.<\/p>\n
Copy downloaded swagger-ui to the public\/apidocs\/api and index.html to public\/apidocs.<\/p>\n
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<\/p>\n
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 \u00e2\u20ac\u0153http:\/\/localhost:3000\/apidocs\/index\u00e2\u20ac\u009d. You can click on available links(show\/hide, List operations, Expand Operations and Raw) on each resource(posts etc):<\/p>\n
\"swagger-doc-1\"<\/a> \"swagger-doc-2\"<\/a><\/p>\n
A lire aussi : Track Changes To Your Model\u2019s Data with Paper Trail Gem<\/a><\/p>\n
Also read  :  Architecture multi-locataire avec sch\u00e9mas PostgreSQL<\/a><\/p>\n
Want to learn more about our Rails development skills and past projects ? Entrer en contact<\/a> with us now !  <\/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
Abonnez-vous pour les derni\u00e8res mises \u00e0 jour<\/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