{"id":18623612,"url":"https://github.com/codica2/rails-api-documentation","last_synced_at":"2025-04-11T03:31:53.895Z","repository":{"id":39678117,"uuid":"187219680","full_name":"codica2/rails-api-documentation","owner":"codica2","description":"Example of how to generate the API documentation in your rails app","archived":false,"fork":false,"pushed_at":"2023-01-19T12:55:06.000Z","size":7237,"stargazers_count":25,"open_issues_count":11,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T09:01:47.398Z","etag":null,"topics":["apipie","documentation","dox","rspec-api-documentation"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codica2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-17T13:18:20.000Z","updated_at":"2025-03-15T21:10:18.000Z","dependencies_parsed_at":"2023-01-28T17:15:46.059Z","dependency_job_id":null,"html_url":"https://github.com/codica2/rails-api-documentation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codica2%2Frails-api-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codica2%2Frails-api-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codica2%2Frails-api-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codica2%2Frails-api-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codica2","download_url":"https://codeload.github.com/codica2/rails-api-documentation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248335492,"owners_count":21086602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apipie","documentation","dox","rspec-api-documentation"],"created_at":"2024-11-07T04:25:19.595Z","updated_at":"2025-04-11T03:31:48.882Z","avatar_url":"https://github.com/codica2.png","language":"Ruby","readme":"# API documentation  \nThis is the example of how to generate the API documentation in your rails app.  \n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/api.jpg\"\u003e  \n\u003c/p\u003e\n\nThis application uses the next gems:\n* [Apipie](https://github.com/Apipie/apipie-rails)\n* [Dox](https://github.com/infinum/dox)\n* [Rspec api documentation](https://github.com/zipmark/rspec_api_documentation)\n\n## APIPIE\nApipie-rails is a DSL and Rails engine for documenting your RESTful API. Instead of traditional use of `#comments`, Apipie lets you describe the code, through the code.\n\n### Getting started\nAdd the gem to your Gemfile\n```ruby\n# Gemfile\ngem 'apipie-rails'\n```\nInstall gem with `bundle install \u0026\u0026 rails g apipie:install`\n\n### Usage\nDescribe allowed params and returned properties in the controller:\n```ruby\n# app/controllers/api/v1/books_controller.rb\n\nmodule Api  \n  module V1  \n    class BooksController \u003c ApplicationController\n\n      def_param_group :book do\n        param :id, :number, desc: 'Books id'\t  \n        param :book, Hash do\n          param :title, String, required: true, desc: 'Books title', only_in: :requiest\n          param :description, String, desc: 'Books description', only_in: :requiest \n        end\n\n        property :title, String, desc: 'Books title'  \n        property :descriprion, String, desc: 'Books description'  \n        property :created_at, String, desc: 'Date of the book creation'  \n        property :updated_at, String, desc: 'Last time the book was updated'\n      end\n      \n    end\t\n  end\nend\n```\n\nThe next step is to describe the HTTP request for your controller actions. Here you can describe the HTTP methods, returned values, response codes, and required params:\n```ruby\n# app/controllers/api/v1/books_controller.rb\n...\napi :GET, '/books/', 'Shows all books'  \nreturns array_of: :book, code: 200, desc: 'All books'  \n\ndef index  \n  books = Book.all  \n  render json: books  \nend\n\napi :POST, '/books/', 'Create a new book'  \nreturns :book, code: 200, desc: 'Created book'  \nparam_group :book  \n\ndef create  \n  book = Book.new(book_params)\n  if book.save  \n    render json: book, status: :ok  \n  else  \n    render json: book.errors, status: :unprocessable_entity  \n  end  \nend\n```\nThat's all! Follow the link [localhost:3000/apipie](http://localhost:3000/apipie) to check the generated API documentation.\n\u003cp align=\"center\"\u003e  \n\t\u003cimg src=\"public/images/screen1.png\" style=\"border: 1px solid grey\"\u003e \n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen2.png\" style=\"border: 1px solid grey\"\u003e  \n\u003c/p\u003e\n\nFor more information please check out [apipie gem documentation]([https://github.com/Apipie/apipie-rails#documentation)\n\n## DOX\nDox generates API documentation from RSpec controller/request specs in a Rails application. It formats the output of the tests in the [API Blueprint](https://apiblueprint.org/) format.\n\n### Getting started\nAdd this line into your Gemfile:\n```ruby\ngroup :test do\n  gem 'dox', require: false\nend\n```\nRun `bundle install`\n\nRequire Dox in the `rails_helper` and configure RSpec:\n```ruby\n# spec/rails_helper.rb\n\nrequire 'dox'\n\nRSpec.configure do |config|\n  config.after(:each, :dox) do |example|\n    example.metadata[:request] = request\n    example.metadata[:response] = response\n  end\nend\n```\nThen configure the Dox:\n```ruby\n\n# spec/rails_helper.rb\n\nDox.configure do |config|\n  config.header_file_path = Rails.root.join('spec/docs/v1/descriptions/header.md')\n  config.desc_folder_path = Rails.root.join('spec/docs/v1/descriptions')\n  config.headers_whitelist = ['Accept', 'X-Auth-Token']\nend\n```\n\nCreate `header.md` by running the command:\n```bash\nmkdir -p ~/spec/docs/v1/descriptions/ \u0026\u0026 echo \"# [Your app name]\" \u003e\u003e header.md\n```\nLoad descriptions in the `rails_helper.rb`: \n```ruby\n# spec/rails_helper.rb\n\nDir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }\n```\n\n### Usage\nDefine a descriptor module for a resource using Dox DSL:\n```ruby\n# spec/docs/v1/books.rb\n  \nmodule Docs    \n  module V1  \n    module Books\n      extend Dox::DSL::Syntax\n      \n      document :api do  \n        resource 'Books' do  \n          endpoint '/books'  \n          group 'Books'  \n        end  \n      end\n\n      document :index do  \n        action 'Index'  \n      end\n    \n      document :create do  \n        action 'Create'  \n      end\n\n    end  \n  end  \nend\n```\n\nInclude the descriptor modules into your specs:\n```ruby\n# spec/request/api/v1/books_spec.rb\n\nrequire 'rails_helper'  \n  \nRSpec.describe 'Book', type: :request do  \n  include Docs::V1::Books::Api\n\n  let!(:books) { create_list(:book, 10) }\n\n  describe 'GET /books/' do  \n    include Docs::V1::Books::Index\n    it 'returns all books', :dox do\n      get '/api/v1/books'\n      expect(response).to be_successful\n      expect(json.count).to eq(books.count)\n    end\n  end\n\n  describe 'POST /books/' do  \n    include Docs::V1::Books::Create  \n    it 'creates a book', :dox do  \n      post '/api/v1/books', params: valid_params  \n      expect(response).to be_successful  \n      expect(json).to have_key('id')  \n      expect(books.count).to be \u003c Book.count  \n    end  \n  end\nend\n```\n\nTo generate documentation run:\n```bash\n-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md\n```\nThe generated documentation path is `public/api/docs/v1/apispec.md` \nWith this command, you can create a rake task for more comfortable usage:\n```ruby\n# lib/tasks/api.rake\n\nnamespace :api do\n  namespace :doc do\n    desc 'Generate API documentation markdown'\n    task :generate do\n      require 'rspec/core/rake_task'\n\n      RSpec::Core::RakeTask.new(:api_spec) do |t|\n        t.pattern = 'spec/request/api/v1/'\n        t.rspec_opts = \"-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md\"\n      end\n\n      Rake::Task['api_spec'].invoke\n    end\n  end\nend\n```\nNow the documentation can be generated by `rake api:doc:generate` command.\n\n### Renderers\nYou can render the HTML by yourself with one of the renderers:\n\n-   [Aglio](https://github.com/danielgtaylor/aglio)\n-   [Snowboard](https://github.com/subosito/snowboard)\n\nBoth of them support multiple themes and template customization.\nOr you can just take your generated markdown and host your documentation on  [Apiary.io](https://apiary.io/)\n\n#### Apiary\nTo use apiary, you need to install [apiary gem](https://github.com/apiaryio/apiary-client)\n```ruby\n# Gemfile\n\ngem 'apiaryio', '~\u003e 0.12.0'\n```\nSign up for [apiary.io](https://apiary.io/) and get your token on API key on [this page](https://login.apiary.io/tokens)\n\nPut your API key to the `.env`:\n```\nAPIARY_API_KEY=\u003cyour_token\u003e\n```\nCreate a new API project:\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen3.png\" style=\"border: 1px solid grey\"\u003e  \n\u003c/p\u003e\n\nCreate a new task to publish your API documentation:\n```ruby\n# lib/tasks/api.rake\n\nnamespace :api do\n  namespace :doc do\n    ...\n    desc 'Publish API documentation to the apiary'\n    task :publish do\n      `apiary publish --path=public/api/docs/v1/apispec.md --api-name=apiary_api_project_name`\n    end\n  \n  end\nend\n```\n\nNow you have well-formatted documentation generated out of the specs to share with your team:\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen4.png\" style=\"border: 1px solid grey\"\u003e  \n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen5.png\" style=\"border: 1px solid grey\"\u003e  \n\u003c/p\u003e\n\nYou can find more info about Dox and Apiary here:\n* [https://github.com/infinum/dox](https://github.com/infinum/dox)\n* [https://github.com/apiaryio/apiary-client](https://github.com/apiaryio/apiary-client)\n\n## RSpec API documentation\n\nGem [rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation) generates API documentation from RSpec like the [dox gem](https://github.com/infinum/dox).\n\n### Getting started\n\nAdd rspec_api_documentation to your Gemfile\n```ruby\ngem 'rspec_api_documentation'\n```\nBundle it:\n```bash\nbundle install\n```\n\n### Usage\nSet up specs:\n```bash\nmkdir spec/acceptance \u0026\u0026 touch spec/acceptance/books_spec.rb\n```\n\nFill your spec file with a code:\n```ruby\n# spec/acceptance/books_spec.rb\nrequire 'rails_helper'  \nrequire 'rspec_api_documentation/dsl'  \n  \nresource 'Books' do  \n  let!(:books) { create_list(:book, 10) }  \n  \n  get '/api/v1/books' do  \n    example_request 'all books' do  \n      expect(status).to eq(200)  \n    end  \n  end\n   \n  post '/api/v1/books' do  \n    parameter :title, scope: :book  \n    parameter :description, scope: :book  \n    let(:title) { Faker::Book.title }  \n    let(:description) { Faker::ChuckNorris.fact }  \n  \n    example_request 'create a book' do  \n      expect(status).to eq(200)  \n    end\n  end  \nend\n```\nGenerate your documentation with:\n```bash\nrake docs:generate\n```\nNow you can find your documentation here `doc/api/index.html`.\n\nIt looks like this:\n\u003cp align=\"center\"\u003e  \n\t\u003cimg src=\"public/images/screen6.png\" style=\"border: 1px solid grey\"\u003e \n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen7.png\" style=\"border: 1px solid grey\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"public/images/screen8.png\" style=\"border: 1px solid grey\"\u003e  \n\u003c/p\u003e\n\nYou can find more info about rspec_api_documentation on [this page](https://github.com/zipmark/rspec_api_documentation)\n\n## License  \nTimebot is Copyright © 2015-2019 Codica. It is released under the [MIT License](https://opensource.org/licenses/MIT).  \n  \n## About Codica  \n  \n[![Codica logo](https://www.codica.com/assets/images/logo/logo.svg)](https://www.codica.com)\n\nThe names and logos for Codica are trademarks of Codica.\n  \nWe love open source software! See [our other projects](https://github.com/codica2) or [hire us](https://www.codica.com/) to design, develop, and grow your product.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodica2%2Frails-api-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodica2%2Frails-api-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodica2%2Frails-api-documentation/lists"}