Basic example of using rspec_api_documentation

posts_spec.rb

require 'acceptance_helper'

resource 'Posts' do
  explanation 'Posts are entities holding some text information.
               They can be created and seen by anyone'
  
  post '/posts' do
    with_options scope: :post do
      parameter :title, 'Title of a post. Can be empty'
      parameter :body, 'Main text of a post. Must be longer than 10 letters', required: true
    end

    response_field :id, 'Id of the created post'
    response_field :title, 'Title of the created post'
    response_field :body, 'Main text of the created post'

    header 'Accept', 'application/json'
    header 'Content-Type', 'application/json'

    let(:title) { 'Foo' }
    let(:body) { 'Lorem ipsum dolor sit amet' }

    example_request 'Creating a post' do
      explanation 'You can create a post by sending its body text and an optional title'

      expect(status).to eq 201

      response = JSON.parse(response_body)
      expect(response['title']).to eq title
      expect(response['body']).to eq body
    end
  end
end