Bloggerly: Document API with rswag

Gemfile

@@ -19,6 +19,8 @@ gem 'active_model_serializers', '~> 0.10.13'
 
 gem 'jwt'
 
+gem 'rswag'
+
 # Bundle edge Rails instead: gem 'rails', github: 'rails/rails', branch: 'main'
 gem 'rails', '~> 7.0.6'
 

Gemfile.lock

@@ -119,6 +119,8 @@ GEM
       actionview (>= 5.0.0)
       activesupport (>= 5.0.0)
     json (2.6.3)
+    json-schema (3.0.0)
+      addressable (>= 2.8)
     jsonapi-renderer (0.2.2)
     jwt (2.7.1)
     language_server-protocol (3.17.0.3)
@@ -223,6 +225,20 @@ GEM
       rspec-mocks (~> 3.12)
       rspec-support (~> 3.12)
     rspec-support (3.12.1)
+    rswag (2.10.1)
+      rswag-api (= 2.10.1)
+      rswag-specs (= 2.10.1)
+      rswag-ui (= 2.10.1)
+    rswag-api (2.10.1)
+      railties (>= 3.1, < 7.1)
+    rswag-specs (2.10.1)
+      activesupport (>= 3.1, < 7.1)
+      json-schema (>= 2.2, < 4.0)
+      railties (>= 3.1, < 7.1)
+      rspec-core (>= 2.14)
+    rswag-ui (2.10.1)
+      actionpack (>= 3.1, < 7.1)
+      railties (>= 3.1, < 7.1)
     rubocop (1.54.2)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -299,6 +315,7 @@ DEPENDENCIES
   rails (~> 7.0.6)
   rails-controller-testing
   rspec-rails
+  rswag
   rubocop (>= 1.0, < 2.0)
   selenium-webdriver
   sprockets-rails

app/controllers/api/v1/comments_controller.rb

@@ -6,6 +6,8 @@ def index
     post = user.posts.find(params[:post_id])
     comments = post.comments
     render json: comments
+  rescue StandardError => e
+    render json: { error: e.message }, status: :bad_request
   end
 
   def create
@@ -18,9 +20,12 @@ def create
       author: user
     )
 
-    new_comment.save
-    render json: { success: 'Comment added!' }
+    if new_comment.save
+      render json: { success: 'Comment added!' }, status: :created
+    else
+      render json: { error: new_comment.errors.full_messages }, status: :bad_request
+    end
   rescue StandardError => e
-    render json: { error: e.message }
+    render json: { error: e.message }, status: :bad_request
   end
 end

app/controllers/api/v1/posts_controller.rb

@@ -3,5 +3,7 @@ def index
     posts = User.find(params['user_id']).posts
 
     render json: posts
+  rescue StandardError
+    render json: { error: 'User not found' }, status: :bad_request
   end
 end

config/initializers/rswag_api.rb

@@ -0,0 +1,14 @@
+Rswag::Api.configure do |c|
+
+  # Specify a root folder where Swagger JSON files are located
+  # This is used by the Swagger middleware to serve requests for API descriptions
+  # NOTE: If you're using rswag-specs to generate Swagger, you'll need to ensure
+  # that it's configured to generate files in the same folder
+  c.swagger_root = Rails.root.to_s + '/swagger'
+
+  # Inject a lambda function to alter the returned Swagger prior to serialization
+  # The function will have access to the rack env for the current request
+  # For example, you could leverage this to dynamically assign the "host" property
+  #
+  #c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
+end

config/initializers/rswag_ui.rb

@@ -0,0 +1,16 @@
+Rswag::Ui.configure do |c|
+
+  # List the Swagger endpoints that you want to be documented through the
+  # swagger-ui. The first parameter is the path (absolute or relative to the UI
+  # host) to the corresponding endpoint and the second is a title that will be
+  # displayed in the document selector.
+  # NOTE: If you're using rspec-api to expose Swagger files
+  # (under swagger_root) as JSON or YAML endpoints, then the list below should
+  # correspond to the relative paths for those endpoints.
+
+  c.swagger_endpoint '/api-docs/v1/swagger.yaml', 'API V1 Docs'
+
+  # Add Basic Auth in case your API is private
+  # c.basic_auth_enabled = true
+  # c.basic_auth_credentials 'username', 'password'
+end

config/routes.rb

@@ -1,4 +1,6 @@
 Rails.application.routes.draw do
+  mount Rswag::Ui::Engine => '/api-docs'
+  mount Rswag::Api::Engine => '/api-docs'
   namespace :api do
     namespace :v1 do
       post 'sessions' => 'sessions#create'

spec/api/v1/comments_controller_spec.rb

@@ -0,0 +1,38 @@
+require 'swagger_helper'
+
+RSpec.describe 'api/v1/comments', type: :request do
+  path '/api/v1/users/{user_id}/posts/{post_id}/comments' do
+    parameter name: 'user_id', in: :path, type: :string, description: 'ID of a user'
+    parameter name: 'post_id', in: :path, type: :string, description: 'ID of a post'
+
+    get 'List all comments on a user\'s post' do
+      tags 'Comments'
+      response 200, 'Successful' do
+        run_test!
+      end
+    end
+
+    post 'Create a comment on a user\'s post' do
+      tags 'Comments'
+      consumes 'application/json'
+
+      parameter name: 'X-Token', in: :header, type: :string, description: 'API token', required: true
+      parameter name: 'text', in: :body, schema: {
+        type: :object,
+        properties: {
+          text: { type: :string }
+        },
+        required: [:text]
+      }
+      description 'Your API token is generated on sign up. It is located on your user profile page.'
+
+      response 201, 'Comment created' do
+        run_test!
+      end
+
+      response 400, 'Comment not created' do
+        run_test!
+      end
+    end
+  end
+end

spec/api/v1/posts_controller_spec.rb

@@ -0,0 +1,18 @@
+require 'swagger_helper'
+
+RSpec.describe 'api/v1/posts', type: :request do
+  path '/api/v1/users/{user_id}/posts' do
+    get 'List all posts for user with user_id' do
+      tags 'Posts'
+      parameter name: 'user_id', in: :path, type: :string, description: 'user_id'
+
+      response 200, 'Successful' do
+        run_test!
+      end
+
+      response 400, 'User not found' do
+        run_test!
+      end
+    end
+  end
+end

spec/swagger_helper.rb

@@ -0,0 +1,41 @@
+require 'rails_helper'
+
+RSpec.configure do |config|
+  # Specify a root folder where Swagger JSON files are generated
+  # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
+  # to ensure that it's configured to serve Swagger from the same folder
+  config.swagger_root = Rails.root.join('swagger').to_s
+
+  # Define one or more Swagger documents and provide global metadata for each one
+  # When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
+  # be generated at the provided relative path under swagger_root
+  # By default, the operations defined in spec files are added to the first
+  # 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' => {
+      openapi: '3.0.1',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      },
+      paths: {},
+      servers: [
+        {
+          url: 'https://{defaultHost}',
+          variables: {
+            defaultHost: {
+              default: 'www.example.com'
+            }
+          }
+        }
+      ]
+    }
+  }
+
+  # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'.
+  # 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
+end

swagger/v1/swagger.yaml

@@ -0,0 +1,77 @@
+---
+openapi: 3.0.1
+info:
+  title: API V1
+  version: v1
+paths:
+  "/api/v1/users/{user_id}/posts/{post_id}/comments":
+    parameters:
+    - name: user_id
+      in: path
+      description: ID of a user
+      required: true
+      schema:
+        type: string
+    - name: post_id
+      in: path
+      description: ID of a post
+      required: true
+      schema:
+        type: string
+    get:
+      summary: List all comments on a user's post
+      tags:
+      - Comments
+      responses:
+        '200':
+          description: Successful
+    post:
+      summary: Create a comment on a user's post
+      tags:
+      - Comments
+      parameters:
+      - name: X-Token
+        in: header
+        description: API token
+        required: true
+        schema:
+          type: string
+      description: Your API token is generated on sign up. It is located on your user
+        profile page.
+      responses:
+        '201':
+          description: Comment created
+        '400':
+          description: Comment not created
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                text:
+                  type: string
+              required:
+              - text
+  "/api/v1/users/{user_id}/posts":
+    get:
+      summary: List all posts for user with user_id
+      tags:
+      - Posts
+      parameters:
+      - name: user_id
+        in: path
+        description: user_id
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: Successful
+        '400':
+          description: User not found
+servers:
+- url: https://{defaultHost}
+  variables:
+    defaultHost:
+      default: www.example.com