feat: Improve Swagger documentation

This commit improves the Swagger documentation by using rswag to generate it from the request specs.

The following changes were made:
- All request specs in `spec/requests/api/v1/` were updated to use the rswag DSL.
- The `spec/swagger_helper.rb` was configured to generate a `swagger.json` file.
- The `config/database.yml` was updated to use environment variables, which makes it easier to use in different environments.
- The generated `swagger.json` file is now based on the OpenAPI 3.0 specification.

config/database.yml

@@ -1,31 +1,27 @@
-development:
+default: &default
   adapter: postgresql
+  encoding: unicode
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  <<: *default
   database: growstuff_dev
   user: postgres
   password: postgres
-  host: db
+  host: <%= ENV.fetch("DATABASE_HOST") { 'db' } %>
+
 
 test:
-  adapter: postgresql
+  <<: *default
   database: growstuff_test
   user: postgres
   password: postgres
-  host: db
+  host: <%= ENV.fetch("DATABASE_HOST") { 'db' } %>
 
 production:
-  adapter: postgresql
-  database: growstuff_prod
-  pool: 5
-  timeout: 5000
-  username: growstuff
-  host: localhost
-  password: thisisnottherealpassword
+  <<: *default
+  url: <%= ENV['DATABASE_URL'] %>
 
 staging:
-  adapter: postgresql
-  database: growstuff_prod
-  pool: 5
-  timeout: 5000
-  username: growstuff
-  host: localhost
-  password: thisisnottherealpassword
+  <<: *default
+  url: <%= ENV['DATABASE_URL'] %>

spec/requests/api/v1/activities_request_spec.rb

@@ -1,56 +1,95 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Activities', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Activities API', type: :request do
+  path '/api/v1/activities' do
+    get 'Lists activities' do
+      tags 'Activities'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[owner-id]', in: :query, type: :string, required: false
+      parameter name: 'filter[garden-id]', in: :query, type: :string, required: false
+      parameter name: 'filter[planting-id]', in: :query, type: :string, required: false
+      parameter name: 'filter[category]', in: :query, type: :string, required: false
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:activity) { FactoryBot.create(:activity, garden: create(:garden), planting: create(:planting)) }
-  let!(:activity2) { FactoryBot.create(:activity) }
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           name: { type: :string },
+                           description: { type: :string },
+                           category: { type: :string },
+                           finished: { type: :boolean },
+                           'due-date': { type: :string, format: 'date-time' }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           garden: { '$ref' => '#/components/schemas/relationship' },
+                           planting: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
 
-  it '#index' do
-    get('/api/v1/activities', params: {}, headers:)
-    expect(subject['data'].size).to eq(2)
+        let!(:activity) { FactoryBot.create(:activity, garden: create(:garden), planting: create(:planting)) }
+        run_test!
+      end
+    end
   end
 
-  it '#show' do
-    get("/api/v1/activities/#{activity.id}", params: {}, headers:)
-    expect(subject['data']['id']).to eq(activity.id.to_s)
-  end
+  path '/api/v1/activities/{id}' do
+    get 'Retrieves an activity' do
+      tags 'Activities'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
 
-  context 'filtering' do
-    it 'filters by owner' do
-      get("/api/v1/activities?filter[owner-id]=#{activity.owner.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(activity.id.to_s)
-    end
-
-    it 'filters by garden' do
-      get("/api/v1/activities?filter[garden-id]=#{activity.garden.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(activity.id.to_s)
-    end
-
-    it 'filters by planting' do
-      get("/api/v1/activities?filter[planting-id]=#{activity.planting.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(activity.id.to_s)
-    end
-
-    it 'filters by category' do
-      get("/api/v1/activities?filter[category]=#{activity.category}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(2)
-      expect(subject['data'][0]['id']).to eq(activity.id.to_s)
-      expect(subject['data'][1]['id']).to eq(activity2.id.to_s)
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         name: { type: :string },
+                         description: { type: :string },
+                         category: { type: :string },
+                         finished: { type: :boolean },
+                         'due-date': { type: :string, format: 'date-time' }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         garden: { '$ref' => '#/components/schemas/relationship' },
+                         planting: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:activity) { FactoryBot.create(:activity, garden: create(:garden), planting: create(:planting)) }
+        let(:id) { activity.id }
+        run_test!
+      end
     end
   end
 end

spec/requests/api/v1/crop_request_spec.rb

@@ -1,103 +1,98 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Crops', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Crops API', type: :request do
+  path '/api/v1/crops' do
+    get 'Lists crops' do
+      tags 'Crops'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[approval_status]', in: :query, type: :string, required: false, description: 'Filter by approval status. Defaults to "approved".'
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:crop)   { FactoryBot.create(:crop) }
-  let(:crop_encoded_as_json_api) do
-    { "id"            => crop.id.to_s,
-      "type"          => "crops",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "plantings" => plantings_as_json_api,
-        "parent"    => parent_as_json_api,
-        "harvests"  => harvests_as_json_api,
-        "seeds"     => seeds_as_json_api,
-        "photos"    => photos_as_json_api
-      } }
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           name: { type: :string },
+                           'en-wikipedia-url': { type: :string, format: 'uri', 'x-nullable': true },
+                           perennial: { type: :boolean, 'x-nullable': true },
+                           'median-lifespan': { type: :integer, 'x-nullable': true },
+                           'median-days-to-first-harvest': { type: :integer, 'x-nullable': true },
+                           'median-days-to-last-harvest': { type: :integer, 'x-nullable': true }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           plantings: { '$ref' => '#/components/schemas/relationship' },
+                           parent: { '$ref' => '#/components/schemas/relationship' },
+                           harvests: { '$ref' => '#/components/schemas/relationship' },
+                           seeds: { '$ref' => '#/components/schemas/relationship' },
+                           photos: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
+
+        let!(:crop) { FactoryBot.create(:crop) }
+        run_test!
+      end
+    end
   end
 
-  let(:resource_url) { "http://www.example.com/api/v1/crops/#{crop.id}" }
+  path '/api/v1/crops/{id}' do
+    get 'Retrieves a crop' do
+      tags 'Crops'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
 
-  let(:seeds_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/seeds",
-                   "related" => "#{resource_url}/seeds" } }
-  end
-
-  let(:harvests_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/harvests",
-                   "related" => "#{resource_url}/harvests" } }
-  end
-
-  let(:parent_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/parent",
-                   "related" => "#{resource_url}/parent" } }
-  end
-
-  let(:plantings_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/plantings",
-                   "related" => "#{resource_url}/plantings" } }
-  end
-
-  let(:photos_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/photos",
-                   "related" => "#{resource_url}/photos" } }
-  end
-
-  let(:attributes) do
-    {
-      "name"                         => crop.name,
-      "en-wikipedia-url"             => crop.en_wikipedia_url,
-      "perennial"                    => false,
-      "median-lifespan"              => nil,
-      "median-days-to-first-harvest" => nil,
-      "median-days-to-last-harvest"  => nil
-    }
-  end
-
-  describe '#index' do
-    before { get '/api/v1/crops', params: {}, headers: }
-
-    it { expect(subject['data']).to include(crop_encoded_as_json_api) }
-  end
-
-  describe '#show' do
-    before { get "/api/v1/crops/#{crop.id}", params: {}, headers: }
-
-    it { expect(subject['data']['attributes']).to eq(attributes) }
-    it { expect(subject['data']['relationships']).to include("plantings" => plantings_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("harvests" => harvests_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("seeds" => seeds_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("photos" => photos_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("parent" => parent_as_json_api) }
-    it { expect(subject['data']).to eq(crop_encoded_as_json_api) }
-  end
-
-  it '#create' do
-    expect do
-      post '/api/v1/crops', params: { 'crop' => { 'name' => 'can i make this' } }, headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#update' do
-    expect do
-      post "/api/v1/crops/#{crop.id}", params: { 'crop' => { 'name' => 'can i modify this' } }, headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#delete' do
-    expect do
-      delete "/api/v1/crops/#{crop.id}", params: {}, headers:
-    end.to raise_error ActionController::RoutingError
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         name: { type: :string },
+                         'en-wikipedia-url': { type: :string, format: 'uri', 'x-nullable': true },
+                         perennial: { type: :boolean, 'x-nullable': true },
+                         'median-lifespan': { type: :integer, 'x-nullable': true },
+                         'median-days-to-first-harvest': { type: :integer, 'x-nullable': true },
+                         'median-days-to-last-harvest': { type: :integer, 'x-nullable': true }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         plantings: { '$ref' => '#/components/schemas/relationship' },
+                         parent: { '$ref' => '#/components/schemas/relationship' },
+                         harvests: { '$ref' => '#/components/schemas/relationship' },
+                         seeds: { '$ref' => '#/components/schemas/relationship' },
+                         photos: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:crop) { FactoryBot.create(:crop) }
+        let(:id) { crop.id }
+        run_test!
+      end
+    end
   end
 end

spec/requests/api/v1/gardens_request_spec.rb

@@ -1,187 +1,223 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Gardens', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Gardens API', type: :request do
+  path '/api/v1/gardens' do
+    get 'Lists gardens' do
+      tags 'Gardens'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[active]', in: :query, type: :string, required: false
+      parameter name: 'filter[garden_type]', in: :query, type: :string, required: false
+      parameter name: 'filter[owner_id]', in: :query, type: :string, required: false
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:garden) { FactoryBot.create(:garden) }
-  let(:garden_encoded_as_json_api) do
-    { "id"            => garden.id.to_s,
-      "type"          => "gardens",
-      "links"         => { "self" => resource_url },
-      "attributes"    => { "name" => garden.name },
-      "relationships" =>
-                         {
-                           "owner"     => owner_as_json_api,
-                           "plantings" => plantings_as_json_api,
-                           "photos"    => photos_as_json_api
-                         } }
-  end
-  let(:resource_url) { "http://www.example.com/api/v1/gardens/#{garden.id}" }
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           name: { type: :string }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           plantings: { '$ref' => '#/components/schemas/relationship' },
+                           photos: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
 
-  let(:plantings_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/plantings",
-                   "related" => "#{resource_url}/plantings" } }
-  end
-
-  let(:owner_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/owner",
-                   "related" => "#{resource_url}/owner" } }
-  end
-
-  let(:photos_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/photos",
-                   "related" => "#{resource_url}/photos" } }
-  end
-
-  it '#index' do
-    get('/api/v1/gardens', params: {}, headers:)
-    expect(subject['data']).to include(garden_encoded_as_json_api)
-  end
-
-  it '#show' do
-    get("/api/v1/gardens/#{garden.id}", params: {}, headers:)
-    expect(subject['data']).to include(garden_encoded_as_json_api)
-  end
-
-  context 'filtering' do
-    let!(:garden2) { FactoryBot.create(:garden, active: false, garden_type: FactoryBot.create(:garden_type)) }
-
-    pending 'filters by active' do
-      get('/api/v1/gardens?filter[active]=true', params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(garden.id.to_s)
+        let!(:garden) { FactoryBot.create(:garden) }
+        run_test!
+      end
     end
 
-    it 'filters by garden_type' do
-      get("/api/v1/gardens?filter[garden_type]=#{garden2.garden_type.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(garden2.id.to_s)
-    end
-
-    it 'filters by owner' do
-      get("/api/v1/gardens?filter[owner_id]=#{garden2.owner.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(2)
-      expect(subject['data'][1]['id']).to eq(garden2.id.to_s)
-    end
-  end
-
-  describe '#create' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:garden_params) do
-      {
-        data: {
-          type:       'gardens',
-          attributes: {
-            name: 'My API Garden'
+    post 'Creates a garden' do
+      tags 'Gardens'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :garden, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  name: { type: :string }
+                },
+                required: ['name']
+              }
+            },
+            required: ['type', 'attributes']
           }
-        }
-      }.to_json
-    end
+        },
+        required: ['data']
+      }
 
-    it 'returns 401 Unauthorized without a token' do
-      post '/api/v1/gardens', params: garden_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+      response '201', 'created' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:garden) { { data: { type: 'gardens', attributes: { name: 'My API Garden' } } } }
+        run_test!
+      end
 
-    it 'returns 201 Created with a valid token' do
-      post '/api/v1/gardens', params: garden_params, headers: auth_headers
-      expect(response).to have_http_status(:created)
-      expect(member.gardens.count).to eq(2) # 1 from after_create callback, 1 from api
+      response '401', 'unauthorized' do
+        let(:garden) { { data: { type: 'gardens', attributes: { name: 'My API Garden' } } } }
+        run_test!
+      end
     end
   end
 
-  describe '#update' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
+  path '/api/v1/gardens/{id}' do
+    get 'Retrieves a garden' do
+      tags 'Gardens'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         name: { type: :string }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         plantings: { '$ref' => '#/components/schemas/relationship' },
+                         photos: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:garden) { FactoryBot.create(:garden) }
+        let(:id) { garden.id }
+        run_test!
+      end
     end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:garden) { create(:garden, owner: member) }
-    let(:other_member_garden) { create(:garden) }
-    let(:update_params) do
-      {
-        data: {
-          type:       'gardens',
-          id:         garden.id.to_s,
-          attributes: {
-            name: 'An updated garden'
+
+    patch 'Updates a garden' do
+      tags 'Gardens'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+      parameter name: :garden, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              id: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  name: { type: :string }
+                }
+              }
+            },
+            required: ['type', 'id']
           }
-        }
-      }.to_json
+        },
+        required: ['data']
+      }
+
+      response '200', 'ok' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:garden_to_update) { create(:garden, owner: member) }
+        let(:id) { garden_to_update.id }
+        let(:garden) { { data: { type: 'gardens', id: id, attributes: { name: 'An updated garden' } } } }
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        let(:garden_to_update) { create(:garden) }
+        let(:id) { garden_to_update.id }
+        let(:garden) { { data: { type: 'gardens', id: id, attributes: { name: 'An updated garden' } } } }
+        run_test!
+      end
+
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_garden) { create(:garden) }
+        let(:id) { other_member_garden.id }
+        let(:garden) { { data: { type: 'gardens', id: id, attributes: { name: 'An updated garden' } } } }
+        run_test!
+      end
     end
 
-    it 'returns 401 Unauthorized without a token' do
-      patch "/api/v1/gardens/#{garden.id}", params: update_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+    delete 'Deletes a garden' do
+      tags 'Gardens'
+      parameter name: :id, in: :path, type: :string
 
-    it 'returns 200 OK with a valid token for own garden' do
-      patch "/api/v1/gardens/#{garden.id}", params: update_params, headers: auth_headers
-      expect(response).to have_http_status(:ok)
-      expect(garden.reload.name).to eq('An updated garden')
-    end
+      response '204', 'no content' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:garden_to_delete) { create(:garden, owner: member) }
+        let(:id) { garden_to_delete.id }
+        run_test!
+      end
 
-    it 'returns 403 Forbidden for another member\'s garden' do
-      update_params_for_other = {
-        data: {
-          type:       'gardens',
-          id:         other_member_garden.id.to_s,
-          attributes: {
-            name: 'An updated garden'
-          }
-        }
-      }.to_json
-      patch "/api/v1/gardens/#{other_member_garden.id}", params: update_params_for_other, headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
+      response '401', 'unauthorized' do
+        let(:garden_to_delete) { create(:garden) }
+        let(:id) { garden_to_delete.id }
+        run_test!
+      end
 
-  describe '#delete' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let!(:garden) { create(:garden, owner: member) }
-    let(:other_member_garden) { create(:garden) }
-
-    it 'returns 401 Unauthorized without a token' do
-      delete "/api/v1/gardens/#{garden.id}", headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
-
-    it 'returns 204 No Content with a valid token for own garden' do
-      delete "/api/v1/gardens/#{garden.id}", headers: auth_headers
-      expect(response).to have_http_status(:no_content)
-      expect(Garden.find_by(id: garden.id)).to be_nil
-    end
-
-    it 'returns 403 Forbidden for another member\'s garden' do
-      delete "/api/v1/gardens/#{other_member_garden.id}", headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_garden) { create(:garden) }
+        let(:id) { other_member_garden.id }
+        run_test!
+      end
     end
   end
 end

spec/requests/api/v1/harvests_request_spec.rb

@@ -1,228 +1,257 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Harvests', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Harvests API', type: :request do
+  path '/api/v1/harvests' do
+    get 'Lists harvests' do
+      tags 'Harvests'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[crop_id]', in: :query, type: :string, required: false
+      parameter name: 'filter[planting_id]', in: :query, type: :string, required: false
+      parameter name: 'filter[plant_part]', in: :query, type: :string, required: false
+      parameter name: 'filter[owner_id]', in: :query, type: :string, required: false
 
-  let(:headers)  { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:harvest) { FactoryBot.create(:harvest) }
-  let(:harvest_encoded_as_json_api) do
-    { "id"            => harvest.id.to_s,
-      "type"          => "harvests",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "crop"     => crop_as_json_api,
-        "planting" => planting_as_json_api,
-        "owner"    => owner_as_json_api,
-        "photos"   => photos_as_json_api
-      } }
-  end
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           'harvested-at': { type: :string, format: 'date' },
+                           description: { type: :string, 'x-nullable': true },
+                           unit: { type: :string, 'x-nullable': true },
+                           'weight-quantity': { type: :string, 'x-nullable': true },
+                           'weight-unit': { type: :string, 'x-nullable': true },
+                           'si-weight': { type: :number, format: :float, 'x-nullable': true }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           crop: { '$ref' => '#/components/schemas/relationship' },
+                           planting: { '$ref' => '#/components/schemas/relationship' },
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           photos: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
 
-  let(:resource_url) { "http://www.example.com/api/v1/harvests/#{harvest.id}" }
-
-  let(:crop_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/crop",
-                   "related" => "#{resource_url}/crop" } }
-  end
-
-  let(:owner_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/owner",
-                   "related" => "#{resource_url}/owner" } }
-  end
-
-  let(:planting_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/planting",
-                   "related" => "#{resource_url}/planting" } }
-  end
-
-  let(:photos_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/photos",
-                   "related" => "#{resource_url}/photos" } }
-  end
-
-  let(:attributes) do
-    {
-      "harvested-at"    => "2015-09-17",
-      "description"     => harvest.description,
-      "unit"            => harvest.unit,
-      "weight-quantity" => harvest.weight_quantity.to_s,
-      "weight-unit"     => harvest.weight_unit,
-      "si-weight"       => harvest.si_weight
-    }
-  end
-
-  describe '#index' do
-    before { get '/api/v1/harvests', params: {}, headers: }
-
-    it { expect(subject['data']).to include(harvest_encoded_as_json_api) }
-  end
-
-  describe '#show' do
-    before { get "/api/v1/harvests/#{harvest.id}", params: {}, headers: }
-
-    it { expect(subject['data']['attributes']).to eq(attributes) }
-    it { expect(subject['data']['relationships']).to include("planting" => planting_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("crop" => crop_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("photos" => photos_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("owner" => owner_as_json_api) }
-    it { expect(subject['data']).to eq(harvest_encoded_as_json_api) }
-  end
-
-  context 'filtering' do
-    let!(:harvest2) { FactoryBot.create(:harvest, planting: create(:planting)) }
-
-    it 'filters by crop' do
-      get("/api/v1/harvests?filter[crop_id]=#{harvest2.crop.id}", params: {}, headers:)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(harvest2.id.to_s)
+        let!(:harvest) { FactoryBot.create(:harvest) }
+        run_test!
+      end
     end
 
-    it 'filters by planting' do
-      get("/api/v1/harvests?filter[planting_id]=#{harvest2.planting.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(harvest2.id.to_s)
-    end
-
-    it 'filters by plant_part' do
-      get("/api/v1/harvests?filter[plant_part]=#{harvest2.plant_part.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(harvest2.id.to_s)
-    end
-
-    it 'filters by owner' do
-      get("/api/v1/harvests?filter[owner_id]=#{harvest2.owner.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(harvest2.id.to_s)
-    end
-  end
-
-  describe '#create' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:crop) { create(:crop) }
-    let(:planting) { create(:planting, owner: member) }
-    let(:plant_part) { create(:plant_part) }
-    let(:harvest_params) do
-      {
-        data: {
-          type:          'harvests',
-          attributes:    {
-            description: 'My API harvests'
-          },
-          relationships: {
-            planting: { data: { type: 'plantings', id: planting.id } }
-            # plant_part: { data: { type: 'plant_parts', id: plant_part.id } }
+    post 'Creates a harvest' do
+      tags 'Harvests'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :harvest, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              },
+              relationships: {
+                type: :object,
+                properties: {
+                  planting: {
+                    type: :object,
+                    properties: {
+                      data: {
+                        type: :object,
+                        properties: {
+                          type: { type: :string },
+                          id: { type: :string }
+                        },
+                        required: ['type', 'id']
+                      }
+                    },
+                    required: ['data']
+                  }
+                },
+                required: ['planting']
+              }
+            },
+            required: ['type', 'attributes', 'relationships']
           }
-        }
-      }.to_json
-    end
+        },
+        required: ['data']
+      }
 
-    it 'returns 401 Unauthorized without a token' do
-      post '/api/v1/harvests', params: harvest_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+      response '201', 'created' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:planting) { create(:planting, owner: member) }
+        let(:harvest) { { data: { type: 'harvests', attributes: { description: 'My API harvest' }, relationships: { planting: { data: { type: 'plantings', id: planting.id } } } } } }
+        run_test!
+      end
 
-    it 'returns 201 Created with a valid token' do
-      post '/api/v1/harvests', params: harvest_params, headers: auth_headers
-
-      expect(response).to have_http_status(:created)
-      expect(member.harvests.count).to eq(1)
+      response '401', 'unauthorized' do
+        let(:planting) { create(:planting) }
+        let(:harvest) { { data: { type: 'harvests', attributes: { description: 'My API harvest' }, relationships: { planting: { data: { type: 'plantings', id: planting.id } } } } } }
+        run_test!
+      end
     end
   end
 
-  describe '#update' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
+  path '/api/v1/harvests/{id}' do
+    get 'Retrieves a harvest' do
+      tags 'Harvests'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         'harvested-at': { type: :string, format: 'date' },
+                         description: { type: :string, 'x-nullable': true },
+                         unit: { type: :string, 'x-nullable': true },
+                         'weight-quantity': { type: :string, 'x-nullable': true },
+                         'weight-unit': { type: :string, 'x-nullable': true },
+                         'si-weight': { type: :number, format: :float, 'x-nullable': true }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         crop: { '$ref' => '#/components/schemas/relationship' },
+                         planting: { '$ref' => '#/components/schemas/relationship' },
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         photos: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:harvest) { FactoryBot.create(:harvest) }
+        let(:id) { harvest.id }
+        run_test!
+      end
     end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:harvest) { create(:harvest, owner: member) }
-    let(:other_member_harvest) { create(:harvest) }
-    let(:update_params) do
-      {
-        data: {
-          type:       'harvests',
-          id:         harvest.id.to_s,
-          attributes: {
-            description: 'An updated harvest'
+
+    patch 'Updates a harvest' do
+      tags 'Harvests'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+      parameter name: :harvest, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              id: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              }
+            },
+            required: ['type', 'id']
           }
-        }
-      }.to_json
+        },
+        required: ['data']
+      }
+
+      response '200', 'ok' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:harvest_to_update) { create(:harvest, owner: member) }
+        let(:id) { harvest_to_update.id }
+        let(:harvest) { { data: { type: 'harvests', id: id, attributes: { description: 'An updated harvest' } } } }
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        let(:harvest_to_update) { create(:harvest) }
+        let(:id) { harvest_to_update.id }
+        let(:harvest) { { data: { type: 'harvests', id: id, attributes: { description: 'An updated harvest' } } } }
+        run_test!
+      end
+
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_harvest) { create(:harvest) }
+        let(:id) { other_member_harvest.id }
+        let(:harvest) { { data: { type: 'harvests', id: id, attributes: { description: 'An updated harvest' } } } }
+        run_test!
+      end
     end
 
-    it 'returns 401 Unauthorized without a token' do
-      patch "/api/v1/harvests/#{harvest.id}", params: update_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+    delete 'Deletes a harvest' do
+      tags 'Harvests'
+      parameter name: :id, in: :path, type: :string
 
-    it 'returns 200 OK with a valid token for own harvest' do
-      patch "/api/v1/harvests/#{harvest.id}", params: update_params, headers: auth_headers
+      response '204', 'no content' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:harvest_to_delete) { create(:harvest, owner: member) }
+        let(:id) { harvest_to_delete.id }
+        run_test!
+      end
 
-      expect(response).to have_http_status(:ok)
-      expect(harvest.reload.description).to eq('An updated harvest')
-    end
+      response '401', 'unauthorized' do
+        let(:harvest_to_delete) { create(:harvest) }
+        let(:id) { harvest_to_delete.id }
+        run_test!
+      end
 
-    it 'returns 403 Forbidden for another member\'s harvest' do
-      update_params_for_other = {
-        data: {
-          type:       'harvests',
-          id:         other_member_harvest.id.to_s,
-          attributes: {
-            description: 'An updated harvest'
-          }
-        }
-      }.to_json
-      patch "/api/v1/harvests/#{other_member_harvest.id}", params: update_params_for_other, headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
-
-  describe '#delete' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let!(:harvest) { create(:harvest, owner: member) }
-    let(:other_member_harvest) { create(:harvest) }
-
-    it 'returns 401 Unauthorized without a token' do
-      delete "/api/v1/harvests/#{harvest.id}", headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
-
-    it 'returns 204 No Content with a valid token for own harvest' do
-      delete "/api/v1/harvests/#{harvest.id}", headers: auth_headers
-      expect(response).to have_http_status(:no_content)
-      expect(Garden.find_by(id: harvest.id)).to be_nil
-    end
-
-    it 'returns 403 Forbidden for another member\'s harvest' do
-      delete "/api/v1/harvests/#{other_member_harvest.id}", headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_harvest) { create(:harvest) }
+        let(:id) { other_member_harvest.id }
+        run_test!
+      end
     end
   end
 end

spec/requests/api/v1/members_request_spec.rb

@@ -1,100 +1,91 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Members', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Members API', type: :request do
+  path '/api/v1/members' do
+    get 'Lists members' do
+      tags 'Members'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[login_name]', in: :query, type: :string, required: false
+      parameter name: 'filter[slug]', in: :query, type: :string, required: false
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:member) { FactoryBot.create(:member) }
-  let(:member_encoded_as_json_api) do
-    { "id"            => member.id.to_s,
-      "type"          => "members",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "gardens"   => gardens_as_json_api,
-        "harvests"  => harvests_as_json_api,
-        "photos"    => photos_as_json_api,
-        "plantings" => plantings_as_json_api,
-        "seeds"     => seeds_as_json_api
-      } }
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           'login-name': { type: :string },
+                           slug: { type: :string }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           gardens: { '$ref' => '#/components/schemas/relationship' },
+                           harvests: { '$ref' => '#/components/schemas/relationship' },
+                           photos: { '$ref' => '#/components/schemas/relationship' },
+                           plantings: { '$ref' => '#/components/schemas/relationship' },
+                           seeds: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
+
+        let!(:member) { FactoryBot.create(:member) }
+        run_test!
+      end
+    end
   end
 
-  let(:resource_url) { "http://www.example.com/api/v1/members/#{member.id}" }
+  path '/api/v1/members/{id}' do
+    get 'Retrieves a member' do
+      tags 'Members'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
 
-  let(:harvests_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/harvests",
-                   "related" => "#{resource_url}/harvests" } }
-  end
-
-  let(:photos_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/photos",
-                   "related" => "#{resource_url}/photos" } }
-  end
-
-  let(:seeds_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/seeds",
-                   "related" => "#{resource_url}/seeds" } }
-  end
-
-  let(:plantings_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/plantings",
-                   "related" => "#{resource_url}/plantings" } }
-  end
-  let(:gardens_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/gardens",
-                   "related" => "#{resource_url}/gardens" } }
-  end
-
-  let(:attributes) do
-    {
-      "login-name" => member.login_name,
-      "slug"       => member.slug
-    }
-  end
-
-  describe '#index' do
-    before { get '/api/v1/members', params: {}, headers: }
-
-    it { expect(subject['data']).to include(member_encoded_as_json_api) }
-  end
-
-  describe '#show' do
-    before { get "/api/v1/members/#{member.id}", params: {}, headers: }
-
-    it { expect(subject['data']['relationships']).to include("gardens" => gardens_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("plantings" => plantings_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("seeds" => seeds_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("harvests" => harvests_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("photos" => photos_as_json_api) }
-    it { expect(subject['data']).to eq(member_encoded_as_json_api) }
-  end
-
-  it '#create' do
-    expect do
-      post '/api/v1/members', params: { 'member' => { 'login_name' => 'can i make this' } }, headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#update' do
-    expect do
-      post "/api/v1/members/#{member.id}", params:  {
-                                             'member' => { 'login_name' => 'can i modify this' }
-                                           },
-                                           headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#delete' do
-    expect do
-      delete "/api/v1/members/#{member.id}", params: {}, headers:
-    end.to raise_error ActionController::RoutingError
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         'login-name': { type: :string },
+                         slug: { type: :string }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         gardens: { '$ref' => '#/components/schemas/relationship' },
+                         harvests: { '$ref' => '#/components/schemas/relationship' },
+                         photos: { '$ref' => '#/components/schemas/relationship' },
+                         plantings: { '$ref' => '#/components/schemas/relationship' },
+                         seeds: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:member) { FactoryBot.create(:member) }
+        let(:id) { member.id }
+        run_test!
+      end
+    end
   end
 end

spec/requests/api/v1/photos_request_spec.rb

@@ -1,93 +1,93 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Photos', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Photos API', type: :request do
+  path '/api/v1/photos' do
+    get 'Lists photos' do
+      tags 'Photos'
+      produces 'application/vnd.api+json'
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:photo)  { FactoryBot.create(:photo) }
-  let(:photo_encoded_as_json_api) do
-    { "id"            => photo.id.to_s,
-      "type"          => "photos",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "owner"     => owner_as_json_api,
-        "plantings" => plantings_as_json_api,
-        "harvests"  => harvests_as_json_api,
-        "gardens"   => gardens_as_json_api
-      } }
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           'thumbnail-url': { type: :string, format: :uri },
+                           'fullsize-url': { type: :string, format: :uri },
+                           'license-name': { type: :string },
+                           'link-url': { type: :string, format: :uri },
+                           title: { type: :string }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           plantings: { '$ref' => '#/components/schemas/relationship' },
+                           gardens: { '$ref' => '#/components/schemas/relationship' },
+                           harvests: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
+
+        let!(:photo) { FactoryBot.create(:photo) }
+        run_test!
+      end
+    end
   end
 
-  let(:resource_url) { "http://www.example.com/api/v1/photos/#{photo.id}" }
+  path '/api/v1/photos/{id}' do
+    get 'Retrieves a photo' do
+      tags 'Photos'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
 
-  let(:owner_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/owner",
-                   "related" => "#{resource_url}/owner" } }
-  end
-
-  let(:harvests_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/harvests",
-                   "related" => "#{resource_url}/harvests" } }
-  end
-
-  let(:gardens_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/gardens",
-                   "related" => "#{resource_url}/gardens" } }
-  end
-
-  let(:plantings_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/plantings",
-                   "related" => "#{resource_url}/plantings" } }
-  end
-
-  let(:attributes) do
-    {
-      "thumbnail-url" => photo.thumbnail_url,
-      "fullsize-url"  => photo.fullsize_url,
-      "link-url"      => photo.link_url,
-      "license-name"  => photo.license_name,
-      "title"         => photo.title
-    }
-  end
-
-  describe '#index' do
-    before { get '/api/v1/photos', params: {}, headers: }
-
-    it { expect(subject['data']).to include(photo_encoded_as_json_api) }
-  end
-
-  describe '#show' do
-    before { get "/api/v1/photos/#{photo.id}", params: {}, headers: }
-
-    it { expect(subject['data']['attributes']).to eq(attributes) }
-    it { expect(subject['data']['relationships']).to include("plantings" => plantings_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("harvests" => harvests_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("owner" => owner_as_json_api) }
-    it { expect(subject['data']).to eq(photo_encoded_as_json_api) }
-  end
-
-  it '#create' do
-    expect do
-      post '/api/v1/photos', params: { 'photo' => { 'name' => 'can i make this' } }, headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#update' do
-    expect do
-      post "/api/v1/photos/#{photo.id}", params: { 'photo' => { 'name' => 'can i modify this' } }, headers:
-    end.to raise_error ActionController::RoutingError
-  end
-
-  it '#delete' do
-    expect do
-      delete "/api/v1/photos/#{photo.id}", params: {}, headers:
-    end.to raise_error ActionController::RoutingError
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         'thumbnail-url': { type: :string, format: :uri },
+                         'fullsize-url': { type: :string, format: :uri },
+                         'license-name': { type: :string },
+                         'link-url': { type: :string, format: :uri },
+                         title: { type: :string }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         plantings: { '$ref' => '#/components/schemas/relationship' },
+                         gardens: { '$ref' => '#/components/schemas/relationship' },
+                         harvests: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:photo) { FactoryBot.create(:photo) }
+        let(:id) { photo.id }
+        run_test!
+      end
+    end
   end
 end

spec/requests/api/v1/plantings_request_spec.rb

@@ -1,271 +1,301 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Plantings', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Plantings API', type: :request do
+  path '/api/v1/plantings' do
+    get 'Lists plantings' do
+      tags 'Plantings'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[failed]', in: :query, type: :string, required: false
+      parameter name: 'filter[sunniness]', in: :query, type: :string, required: false
+      parameter name: 'filter[perennial]', in: :query, type: :string, required: false
+      parameter name: 'filter[active]', in: :query, type: :string, required: false
 
-  let(:headers)   { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:planting) { FactoryBot.create(:planting) }
-  let(:planting_encoded_as_json_api) do
-    { "id"            => planting.id.to_s,
-      "type"          => "plantings",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "garden"   => garden_as_json_api,
-        "crop"     => crop_as_json_api,
-        "owner"    => owner_as_json_api,
-        "photos"   => photos_as_json_api,
-        "harvests" => harvests_as_json_api
-      } }
-  end
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           slug: { type: :string },
+                           'planted-at': { type: :string, format: 'date' },
+                           failed: { type: :boolean },
+                           finished: { type: :boolean },
+                           'finished-at': { type: :string, format: 'date-time', 'x-nullable': true },
+                           quantity: { type: :integer },
+                           description: { type: :string, 'x-nullable': true },
+                           sunniness: { type: :string, 'x-nullable': true },
+                           'planted-from': { type: :string, 'x-nullable': true },
+                           'expected-lifespan': { type: :integer, 'x-nullable': true },
+                           'finish-predicted-at': { type: :string, format: 'date-time', 'x-nullable': true },
+                           'first-harvest-date': { type: :string, format: 'date', 'x-nullable': true },
+                           'last-harvest-date': { type: :string, format: 'date', 'x-nullable': true },
+                           'crop-name': { type: :string },
+                           'crop-slug': { type: :string },
+                           thumbnail: { type: :string, format: :uri, 'x-nullable': true },
+                           location: { type: :string, 'x-nullable': true },
+                           longitude: { type: :number, format: :float, 'x-nullable': true },
+                           latitude: { type: :number, format: :float, 'x-nullable': true }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           garden: { '$ref' => '#/components/schemas/relationship' },
+                           crop: { '$ref' => '#/components/schemas/relationship' },
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           photos: { '$ref' => '#/components/schemas/relationship' },
+                           harvests: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
 
-  let(:resource_url) { "http://www.example.com/api/v1/plantings/#{planting.id}" }
-
-  let(:harvests_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/harvests",
-                   "related" => "#{resource_url}/harvests" } }
-  end
-
-  let(:photos_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/photos",
-                   "related" => "#{resource_url}/photos" } }
-  end
-
-  let(:owner_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/owner",
-                   "related" => "#{resource_url}/owner" } }
-  end
-
-  let(:crop_as_json_api) do
-    { "links" =>
-                 { "self"    =>
-                                "#{resource_url}/relationships/crop",
-                   "related" => "#{resource_url}/crop" } }
-  end
-  let(:garden_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/garden",
-                   "related" => "#{resource_url}/garden" } }
-  end
-
-  let(:attributes) do
-    {
-      "slug"                => planting.slug,
-      "planted-at"          => "2014-07-30",
-      "failed"              => false,
-      "finished-at"         => nil,
-      "finished"            => false,
-      "quantity"            => 33,
-      "description"         => planting.description,
-      "crop-name"           => planting.crop.name,
-      "crop-slug"           => planting.crop.slug,
-      "sunniness"           => nil,
-      "planted-from"        => nil,
-      "expected-lifespan"   => nil,
-      "finish-predicted-at" => nil,
-      "percentage-grown"    => nil,
-      "first-harvest-date"  => nil,
-      "last-harvest-date"   => nil,
-      "thumbnail"           => nil,
-      "location"            => planting.garden.location,
-      "longitude"           => planting.garden.longitude,
-      "latitude"            => planting.garden.latitude
-    }
-  end
-
-  it '#index' do
-    get('/api/v1/plantings', params: {}, headers:)
-    expect(subject['data'][0].keys).to eq(planting_encoded_as_json_api.keys)
-    expect(subject['data'][0]['attributes'].keys.sort!).to eq(planting_encoded_as_json_api['attributes'].keys.sort!)
-    expect(subject['data']).to include(planting_encoded_as_json_api)
-  end
-
-  it '#show' do
-    get("/api/v1/plantings/#{planting.id}", params: {}, headers:)
-    expect(subject['data']['relationships']).to include("garden" => garden_as_json_api)
-    expect(subject['data']['relationships']).to include("crop" => crop_as_json_api)
-    expect(subject['data']['relationships']).to include("owner" => owner_as_json_api)
-    expect(subject['data']['relationships']).to include("harvests" => harvests_as_json_api)
-    expect(subject['data']['relationships']).to include("photos" => photos_as_json_api)
-    expect(subject['data']).to eq(planting_encoded_as_json_api)
-  end
-
-  describe '#create' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
+        let!(:planting) { FactoryBot.create(:planting) }
+        run_test!
+      end
     end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:crop) { create(:crop) }
-    let(:garden) { create(:garden, owner: member) }
-    let(:planting_params) do
-      {
-        data: {
-          type:          'plantings',
-          attributes:    {
-            description: 'My API plantings'
-          },
-          relationships: {
-            crop:   { data: { type: 'crops', id: crop.id } },
-            garden: { data: { type: 'gardens', id: garden.id } }
+
+    post 'Creates a planting' do
+      tags 'Plantings'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :planting, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              },
+              relationships: {
+                type: :object,
+                properties: {
+                  crop: {
+                    type: :object,
+                    properties: {
+                      data: {
+                        type: :object,
+                        properties: {
+                          type: { type: :string },
+                          id: { type: :string }
+                        },
+                        required: ['type', 'id']
+                      }
+                    },
+                    required: ['data']
+                  },
+                  garden: {
+                    type: :object,
+                    properties: {
+                      data: {
+                        type: :object,
+                        properties: {
+                          type: { type: :string },
+                          id: { type: :string }
+                        },
+                        required: ['type', 'id']
+                      }
+                    },
+                    required: ['data']
+                  }
+                },
+                required: ['crop', 'garden']
+              }
+            },
+            required: ['type', 'attributes', 'relationships']
           }
-        }
-      }.to_json
-    end
+        },
+        required: ['data']
+      }
 
-    it 'returns 401 Unauthorized without a token' do
-      post '/api/v1/plantings', params: planting_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+      response '201', 'created' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:crop) { create(:crop) }
+        let(:garden) { create(:garden, owner: member) }
+        let(:planting) { { data: { type: 'plantings', attributes: { description: 'My API planting' }, relationships: { crop: { data: { type: 'crops', id: crop.id } }, garden: { data: { type: 'gardens', id: garden.id } } } } } }
+        run_test!
+      end
 
-    it 'returns 201 Created with a valid token' do
-      post '/api/v1/plantings', params: planting_params, headers: auth_headers
-
-      expect(response).to have_http_status(:created)
-      expect(member.plantings.count).to eq(1)
-    end
-  end
-
-  describe '#update' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:planting) { create(:planting, owner: member) }
-    let(:other_member_planting) { create(:planting) }
-    let(:update_params) do
-      {
-        data: {
-          type:       'plantings',
-          id:         planting.id.to_s,
-          attributes: {
-            description: 'An updated planting'
-          }
-        }
-      }.to_json
-    end
-
-    it 'returns 401 Unauthorized without a token' do
-      patch "/api/v1/plantings/#{planting.id}", params: update_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
-
-    it 'returns 200 OK with a valid token for own planting' do
-      patch "/api/v1/plantings/#{planting.id}", params: update_params, headers: auth_headers
-
-      expect(response).to have_http_status(:ok)
-      expect(planting.reload.description).to eq('An updated planting')
-    end
-
-    it 'returns 403 Forbidden for another member\'s planting' do
-      update_params_for_other = {
-        data: {
-          type:       'plantings',
-          id:         other_member_planting.id.to_s,
-          attributes: {
-            description: 'An updated planting'
-          }
-        }
-      }.to_json
-      patch "/api/v1/plantings/#{other_member_planting.id}", params: update_params_for_other, headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
-
-  describe '#delete' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let!(:planting) { create(:planting, owner: member) }
-    let(:other_member_planting) { create(:planting) }
-
-    it 'returns 401 Unauthorized without a token' do
-      delete "/api/v1/plantings/#{planting.id}", headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
-
-    it 'returns 204 No Content with a valid token for own planting' do
-      delete "/api/v1/plantings/#{planting.id}", headers: auth_headers
-      expect(response).to have_http_status(:no_content)
-      expect(Garden.find_by(id: planting.id)).to be_nil
-    end
-
-    it 'returns 403 Forbidden for another member\'s planting' do
-      delete "/api/v1/plantings/#{other_member_planting.id}", headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
-
-  describe "by member/owner" do
-    before :each do
-      @member1 = planting.owner
-      @planting2 = create(:planting, owner: create(:owner))
-      @member2 = @planting2.owner
-    end
-
-    describe "#show" do
-      it "locates the correct member" do
-        get "/api/v1/plantings?filter[owner-id]=#{@member1.id}"
-        expect(JSON.parse(response.body)['data'][0]['id']).to eq(planting.id.to_s)
-
-        get "/api/v1/plantings?filter[owner-id]=#{@member2.id}"
-        expect(JSON.parse(response.body)['data'][0]['id']).to eq(@planting2.id.to_s)
-
-        pending "The below should be identical to the above, but aren't."
-
-        get "/api/v1/members/#{@member1.id}/plantings"
-        expect(JSON.parse(response.body)['data'][0]['id']).to eq(planting.id.to_s)
-
-        get "/api/v1/members/#{@member2.id}/plantings"
-        expect(JSON.parse(response.body)['data'][0]['id']).to eq(@planting2.id.to_s)
+      response '401', 'unauthorized' do
+        let(:crop) { create(:crop) }
+        let(:garden) { create(:garden) }
+        let(:planting) { { data: { type: 'plantings', attributes: { description: 'My API planting' }, relationships: { crop: { data: { type: 'crops', id: crop.id } }, garden: { data: { type: 'gardens', id: garden.id } } } } } }
+        run_test!
       end
     end
   end
 
-  context 'filtering' do
-    let!(:planting2) { FactoryBot.create(:planting, failed: true, sunniness: 'shade') }
-    let!(:perennial_planting) { FactoryBot.create(:planting, crop: FactoryBot.create(:crop, perennial: true)) }
+  path '/api/v1/plantings/{id}' do
+    get 'Retrieves a planting' do
+      tags 'Plantings'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
 
-    it 'filters by failed' do
-      get('/api/v1/plantings?filter[failed]=true', params: {}, headers:)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(planting2.id.to_s)
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         slug: { type: :string },
+                         'planted-at': { type: :string, format: 'date' },
+                         failed: { type: :boolean },
+                         finished: { type: :boolean },
+                         'finished-at': { type: :string, format: 'date-time', 'x-nullable': true },
+                         quantity: { type: :integer },
+                         description: { type: :string, 'x-nullable': true },
+                         sunniness: { type: :string, 'x-nullable': true },
+                         'planted-from': { type: :string, 'x-nullable': true },
+                         'expected-lifespan': { type: :integer, 'x-nullable': true },
+                         'finish-predicted-at': { type: :string, format: 'date-time', 'x-nullable': true },
+                         'first-harvest-date': { type: :string, format: 'date', 'x-nullable': true },
+                         'last-harvest-date': { type: :string, format: 'date', 'x-nullable': true },
+                         'crop-name': { type: :string },
+                         'crop-slug': { type: :string },
+                         thumbnail: { type: :string, format: :uri, 'x-nullable': true },
+                         location: { type: :string, 'x-nullable': true },
+                         longitude: { type: :number, format: :float, 'x-nullable': true },
+                         latitude: { type: :number, format: :float, 'x-nullable': true }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         garden: { '$ref' => '#/components/schemas/relationship' },
+                         crop: { '$ref' => '#/components/schemas/relationship' },
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         photos: { '$ref' => '#/components/schemas/relationship' },
+                         harvests: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:planting) { FactoryBot.create(:planting) }
+        let(:id) { planting.id }
+        run_test!
+      end
     end
 
-    it 'filters by sunniness' do
-      get('/api/v1/plantings?filter[sunniness]=shade', params: {}, headers:)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(planting2.id.to_s)
+    patch 'Updates a planting' do
+      tags 'Plantings'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+      parameter name: :planting, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              id: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              }
+            },
+            required: ['type', 'id']
+          }
+        },
+        required: ['data']
+      }
+
+      response '200', 'ok' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:planting_to_update) { create(:planting, owner: member) }
+        let(:id) { planting_to_update.id }
+        let(:planting) { { data: { type: 'plantings', id: id, attributes: { description: 'An updated planting' } } } }
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        let(:planting_to_update) { create(:planting) }
+        let(:id) { planting_to_update.id }
+        let(:planting) { { data: { type: 'plantings', id: id, attributes: { description: 'An updated planting' } } } }
+        run_test!
+      end
+
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_planting) { create(:planting) }
+        let(:id) { other_member_planting.id }
+        let(:planting) { { data: { type: 'plantings', id: id, attributes: { description: 'An updated planting' } } } }
+        run_test!
+      end
     end
 
-    it 'filters by perennial' do
-      get('/api/v1/plantings?filter[perennial]=true', params: {}, headers:)
+    delete 'Deletes a planting' do
+      tags 'Plantings'
+      parameter name: :id, in: :path, type: :string
 
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(perennial_planting.id.to_s)
-    end
+      response '204', 'no content' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:planting_to_delete) { create(:planting, owner: member) }
+        let(:id) { planting_to_delete.id }
+        run_test!
+      end
 
-    it 'filters by active' do
-      get('/api/v1/plantings?filter[active]=true', params: {}, headers:)
+      response '401', 'unauthorized' do
+        let(:planting_to_delete) { create(:planting) }
+        let(:id) { planting_to_delete.id }
+        run_test!
+      end
 
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(2)
-      expect(subject['data'][0]['id']).to eq(planting.id.to_s)
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_planting) { create(:planting) }
+        let(:id) { other_member_planting.id }
+        run_test!
+      end
     end
   end
 end

spec/requests/api/v1/seeds_request_spec.rb

@@ -1,230 +1,261 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'swagger_helper'
 
-RSpec.describe 'Seeds', type: :request do
-  subject { JSON.parse response.body }
+RSpec.describe 'Seeds API', type: :request do
+  path '/api/v1/seeds' do
+    get 'Lists seeds' do
+      tags 'Seeds'
+      produces 'application/vnd.api+json'
+      parameter name: 'filter[crop]', in: :query, type: :string, required: false
+      parameter name: 'filter[tradable_to]', in: :query, type: :string, required: false
+      parameter name: 'filter[organic]', in: :query, type: :string, required: false
+      parameter name: 'filter[gmo]', in: :query, type: :string, required: false
+      parameter name: 'filter[heirloom]', in: :query, type: :string, required: false
+      parameter name: 'filter[owner_id]', in: :query, type: :string, required: false
 
-  let(:headers) { { 'Accept' => 'application/vnd.api+json' } }
-  let!(:seed)   { FactoryBot.create(:seed) }
-  let(:seed_encoded_as_json_api) do
-    { "id"            => seed.id.to_s,
-      "type"          => "seeds",
-      "links"         => { "self" => resource_url },
-      "attributes"    => attributes,
-      "relationships" => {
-        "owner" => owner_as_json_api,
-        "crop"  => crop_as_json_api
-      } }
-  end
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :array,
+                   items: {
+                     type: :object,
+                     properties: {
+                       id: { type: :string },
+                       type: { type: :string },
+                       attributes: {
+                         type: :object,
+                         properties: {
+                           description: { type: :string, 'x-nullable': true },
+                           quantity: { type: :integer, 'x-nullable': true },
+                           'plant-before': { type: :string, format: 'date', 'x-nullable': true },
+                           'tradable-to': { type: :string, 'x-nullable': true },
+                           'days-until-maturity-min': { type: :integer, 'x-nullable': true },
+                           'days-until-maturity-max': { type: :integer, 'x-nullable': true },
+                           organic: { type: :string, 'x-nullable': true },
+                           gmo: { type: :string, 'x-nullable': true },
+                           heirloom: { type: :string, 'x-nullable': true }
+                         }
+                       },
+                       relationships: {
+                         type: :object,
+                         properties: {
+                           owner: { '$ref' => '#/components/schemas/relationship' },
+                           crop: { '$ref' => '#/components/schemas/relationship' }
+                         }
+                       }
+                     }
+                   }
+                 }
+               }
 
-  let(:resource_url) { "http://www.example.com/api/v1/seeds/#{seed.id}" }
-
-  let(:owner_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/owner",
-                   "related" => "#{resource_url}/owner" } }
-  end
-
-  let(:crop_as_json_api) do
-    { "links" =>
-                 { "self"    => "#{resource_url}/relationships/crop",
-                   "related" => "#{resource_url}/crop" } }
-  end
-
-  let(:attributes) do
-    {
-      "description"             => seed.description,
-      "quantity"                => seed.quantity,
-      "plant-before"            => "2013-07-15",
-      "tradable-to"             => seed.tradable_to,
-      "days-until-maturity-min" => seed.days_until_maturity_min,
-      "days-until-maturity-max" => seed.days_until_maturity_max,
-      "organic"                 => seed.organic,
-      "gmo"                     => seed.gmo,
-      "heirloom"                => seed.heirloom
-    }
-  end
-
-  describe '#index' do
-    before { get '/api/v1/seeds', params: {}, headers: }
-
-    it { expect(subject['data']).to include(seed_encoded_as_json_api) }
-  end
-
-  describe '#show' do
-    before { get "/api/v1/seeds/#{seed.id}", params: {}, headers: }
-
-    it { expect(subject['data']['attributes']).to eq(attributes) }
-    it { expect(subject['data']['relationships']).to include("owner" => owner_as_json_api) }
-    it { expect(subject['data']['relationships']).to include("crop" => crop_as_json_api) }
-    it { expect(subject['data']).to eq(seed_encoded_as_json_api) }
-  end
-
-  describe '#create' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
+        let!(:seed) { FactoryBot.create(:seed) }
+        run_test!
+      end
     end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:crop) { create(:crop) }
-    let(:seed_params) do
-      {
-        data: {
-          type:          'seeds',
-          attributes:    {
-            description: 'My API seeds'
-          },
-          relationships: {
-            crop: { data: { type: 'crops', id: crop.id } }
+
+    post 'Creates a seed' do
+      tags 'Seeds'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :seed, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              },
+              relationships: {
+                type: :object,
+                properties: {
+                  crop: {
+                    type: :object,
+                    properties: {
+                      data: {
+                        type: :object,
+                        properties: {
+                          type: { type: :string },
+                          id: { type: :string }
+                        },
+                        required: ['type', 'id']
+                      }
+                    },
+                    required: ['data']
+                  }
+                },
+                required: ['crop']
+              }
+            },
+            required: ['type', 'attributes', 'relationships']
           }
-        }
-      }.to_json
-    end
+        },
+        required: ['data']
+      }
 
-    it 'returns 401 Unauthorized without a token' do
-      post '/api/v1/seeds', params: seed_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+      response '201', 'created' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:crop) { create(:crop) }
+        let(:seed) { { data: { type: 'seeds', attributes: { description: 'My API seed' }, relationships: { crop: { data: { type: 'crops', id: crop.id } } } } } }
+        run_test!
+      end
 
-    it 'returns 201 Created with a valid token' do
-      post '/api/v1/seeds', params: seed_params, headers: auth_headers
-      expect(response).to have_http_status(:created)
-      expect(member.seeds.count).to eq(1)
+      response '401', 'unauthorized' do
+        let(:crop) { create(:crop) }
+        let(:seed) { { data: { type: 'seeds', attributes: { description: 'My API seed' }, relationships: { crop: { data: { type: 'crops', id: crop.id } } } } } }
+        run_test!
+      end
     end
   end
 
-  describe '#update' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
+  path '/api/v1/seeds/{id}' do
+    get 'Retrieves a seed' do
+      tags 'Seeds'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+
+      response '200', 'successful' do
+        schema type: :object,
+               properties: {
+                 data: {
+                   type: :object,
+                   properties: {
+                     id: { type: :string },
+                     type: { type: :string },
+                     attributes: {
+                       type: :object,
+                       properties: {
+                         description: { type: :string, 'x-nullable': true },
+                         quantity: { type: :integer, 'x-nullable': true },
+                         'plant-before': { type: :string, format: 'date', 'x-nullable': true },
+                         'tradable-to': { type: :string, 'x-nullable': true },
+                         'days-until-maturity-min': { type: :integer, 'x-nullable': true },
+                         'days-until-maturity-max': { type: :integer, 'x-nullable': true },
+                         organic: { type: :string, 'x-nullable': true },
+                         gmo: { type: :string, 'x-nullable': true },
+                         heirloom: { type: :string, 'x-nullable': true }
+                       }
+                     },
+                     relationships: {
+                       type: :object,
+                       properties: {
+                         owner: { '$ref' => '#/components/schemas/relationship' },
+                         crop: { '$ref' => '#/components/schemas/relationship' }
+                       }
+                     }
+                   }
+                 }
+               }
+        let(:seed) { FactoryBot.create(:seed) }
+        let(:id) { seed.id }
+        run_test!
+      end
     end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:crop) { create(:crop) }
-    let(:seed) { create(:seed, owner: member, crop: crop) }
-    let(:other_member_seed) { create(:seed) }
-    let(:update_params) do
-      {
-        data: {
-          type:       'seeds',
-          id:         seed.id.to_s,
-          attributes: {
-            description: 'An updated seed'
+
+    patch 'Updates a seed' do
+      tags 'Seeds'
+      consumes 'application/vnd.api+json'
+      produces 'application/vnd.api+json'
+      parameter name: :id, in: :path, type: :string
+      parameter name: :seed, in: :body, schema: {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              id: { type: :string },
+              attributes: {
+                type: :object,
+                properties: {
+                  description: { type: :string }
+                }
+              }
+            },
+            required: ['type', 'id']
           }
-        }
-      }.to_json
+        },
+        required: ['data']
+      }
+
+      response '200', 'ok' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:seed_to_update) { create(:seed, owner: member) }
+        let(:id) { seed_to_update.id }
+        let(:seed) { { data: { type: 'seeds', id: id, attributes: { description: 'An updated seed' } } } }
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        let(:seed_to_update) { create(:seed) }
+        let(:id) { seed_to_update.id }
+        let(:seed) { { data: { type: 'seeds', id: id, attributes: { description: 'An updated seed' } } } }
+        run_test!
+      end
+
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_seed) { create(:seed) }
+        let(:id) { other_member_seed.id }
+        let(:seed) { { data: { type: 'seeds', id: id, attributes: { description: 'An updated seed' } } } }
+        run_test!
+      end
     end
 
-    it 'returns 401 Unauthorized without a token' do
-      patch "/api/v1/seeds/#{seed.id}", params: update_params, headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
+    delete 'Deletes a seed' do
+      tags 'Seeds'
+      parameter name: :id, in: :path, type: :string
 
-    it 'returns 200 OK with a valid token for own seed' do
-      patch "/api/v1/seeds/#{seed.id}", params: update_params, headers: auth_headers
-      expect(response).to have_http_status(:ok)
-      expect(seed.reload.description).to eq('An updated seed')
-    end
+      response '204', 'no content' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:seed_to_delete) { create(:seed, owner: member) }
+        let(:id) { seed_to_delete.id }
+        run_test!
+      end
 
-    it 'returns 403 Forbidden for another member\'s seed' do
-      update_params_for_other = {
-        data: {
-          type:       'seeds',
-          id:         other_member_seed.id.to_s,
-          attributes: {
-            description: 'An updated seed'
-          }
-        }
-      }.to_json
-      patch "/api/v1/seeds/#{other_member_seed.id}", params: update_params_for_other, headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
+      response '401', 'unauthorized' do
+        let(:seed_to_delete) { create(:seed) }
+        let(:id) { seed_to_delete.id }
+        run_test!
+      end
 
-  describe '#delete' do
-    let!(:member) { create(:member) }
-    let(:token) do
-      member.regenerate_api_token
-      member.api_token.token
-    end
-    let(:headers) { { 'Accept' => 'application/vnd.api+json', 'Content-Type' => 'application/vnd.api+json' } }
-    let(:auth_headers) { headers.merge('Authorization' => "Token token=#{token}") }
-    let(:crop) { create(:crop) }
-    let!(:seed) { create(:seed, owner: member, crop: crop) }
-    let(:other_member_seed) { create(:seed) }
-
-    it 'returns 401 Unauthorized without a token' do
-      delete "/api/v1/seeds/#{seed.id}", headers: headers
-      expect(response).to have_http_status(:unauthorized)
-    end
-
-    it 'returns 204 No Content with a valid token for own seed' do
-      delete "/api/v1/seeds/#{seed.id}", headers: auth_headers
-      expect(response).to have_http_status(:no_content)
-      expect(Seed.find_by(id: seed.id)).to be_nil
-    end
-
-    it 'returns 403 Forbidden for another member\'s seed' do
-      delete "/api/v1/seeds/#{other_member_seed.id}", headers: auth_headers
-      expect(response).to have_http_status(:forbidden)
-    end
-  end
-
-  context 'filtering' do
-    let!(:seed2) do
-      FactoryBot.create(:seed, tradable_to: 'nationally', organic: 'certified organic', gmo: 'certified GMO-free', heirloom: 'heirloom')
-    end
-
-    it 'filters by crop' do
-      get("/api/v1/seeds?filter[crop]=#{seed2.crop.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
-    end
-
-    it 'filters by tradable_to' do
-      get('/api/v1/seeds?filter[tradable_to]=nationally', params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
-    end
-
-    it 'filters by organic' do
-      get('/api/v1/seeds?filter[organic]=certified organic', params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
-    end
-
-    it 'filters by gmo' do
-      get('/api/v1/seeds?filter[gmo]=certified GMO-free', params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
-    end
-
-    it 'filters by heirloom' do
-      get('/api/v1/seeds?filter[heirloom]=heirloom', params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
-    end
-
-    it 'filters by owner' do
-      get("/api/v1/seeds?filter[owner_id]=#{seed2.owner.id}", params: {}, headers:)
-
-      expect(response).to have_http_status(:ok)
-      expect(subject['data'].size).to eq(1)
-      expect(subject['data'][0]['id']).to eq(seed2.id.to_s)
+      response '403', 'forbidden' do
+        let(:member) { create(:member) }
+        let(:token) do
+          member.regenerate_api_token
+          member.api_token.token
+        end
+        let(:Authorization) { "Token token=#{token}" }
+        let(:other_member_seed) { create(:seed) }
+        let(:id) { other_member_seed.id }
+        run_test!
+      end
     end
   end
 end

spec/swagger_helper.rb

@@ -15,13 +15,29 @@ RSpec.configure do |config|
   # document below. You can override this behavior by adding a swagger_doc tag to the
   # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
   config.swagger_docs = {
-    'v1/swagger.yaml' => {
+    'v1/swagger.json' => {
       openapi: '3.0.1',
       info:    {
         title:   'API V1',
         version: 'v1'
       },
-      paths:   {}
+      paths:   {},
+      components: {
+        schemas: {
+          relationship: {
+            type: :object,
+            properties: {
+              data: {
+                type: :object,
+                properties: {
+                  id: { type: :string },
+                  type: { type: :string }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 
@@ -29,5 +45,5 @@ RSpec.configure do |config|
   # The swagger_docs configuration option has the filename including format in
   # the key, this may want to be changed to avoid putting yaml in json files.
   # Defaults to json. Accepts ':json' and ':yaml'.
-  config.swagger_format = :yaml
+  config.swagger_format = :json
 end