Merge pull request #13 from cosywasswa/api-documentation

Api documentation

Gemfile

@@ -13,6 +13,8 @@ gem 'devise'
 
 gem 'cancancan'
 
+gem 'rswag'
+
 # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
 gem 'rails', '~> 7.0.8'
 

Gemfile.lock

@@ -114,6 +114,8 @@ GEM
       actionview (>= 5.0.0)
       activesupport (>= 5.0.0)
     json (2.6.3)
+    json-schema (3.0.0)
+      addressable (>= 2.8)
     language_server-protocol (3.17.0.3)
     loofah (2.21.3)
       crass (~> 1.0.2)
@@ -216,6 +218,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.56.3)
       base64 (~> 0.1.1)
       json (~> 2.3)
@@ -288,6 +304,7 @@ DEPENDENCIES
   rails (~> 7.0.8)
   rails-controller-testing
   rspec-rails
+  rswag
   rubocop (>= 1.0, < 2.0)
   selenium-webdriver
   sprockets-rails

README.md

@@ -57,6 +57,7 @@ Blog-app is a fully functioning website that show the list of posts and empower
 - **Add-devise**
 - **Add-authorization rules**
 - **Add-endpoint for posts and comments**
+- **API docummentation**
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -121,7 +122,6 @@ it will install the required gemfile for running the project
 <!-- FUTURE FEATURES -->
 
 ## 🔭 Future Features <a name="future-features"></a>
- - API documentation.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 

config/database.yml

@@ -21,7 +21,7 @@ default: &default
   # https://guides.rubyonrails.org/configuring.html#database-pooling
   pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
   user: postgres
-  password: manzi
+  password: Wasswa2023
 
 development:
   <<: *default

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'
   devise_for :users
   root to: 'users#index'
   resources :users, only: [:index, :show] do

spec/api/comment_api_spec.rb

@@ -0,0 +1,30 @@
+require 'swagger_helper'
+
+describe 'Comments API' do
+  path '/users/{user_id}/posts/{post_id}/comments' do
+    parameter name: 'user_id', in: :path, type: :integer, required: true, description: 'User ID'
+    parameter name: 'post_id', in: :path, type: :integer, required: true, description: 'Post ID'
+    get 'Retrieve all comments of a post' do
+      tags 'Comments'
+      produces 'application/json'
+      response '200', 'OK' do
+        run_test!
+      end
+    end
+    post 'Create a new comment for a post' do
+      tags 'Comments'
+      consumes 'application/json'
+      parameter name: :comment, in: :body, schema: {
+        type: :object,
+        properties: {
+          text: { type: :string }
+        },
+        required: ['text']
+      }
+      response '201', 'Created' do
+        let(:comment) { { text: 'string' } }
+        run_test!
+      end
+    end
+  end
+end

spec/api/posts_api_spec.rb

@@ -0,0 +1,14 @@
+require 'swagger_helper'
+
+describe 'Posts API' do
+  path '/users/{user_id}/posts' do
+    parameter name: 'user_id', in: :path, type: :integer, required: true, description: 'User ID'
+    get 'Retrieve all the posts of a user' do
+      tags 'Posts'
+      produces 'application/json'
+      response '200', 'OK' 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,65 @@
+---
+openapi: 3.0.1
+info:
+  title: API V1
+  version: v1
+paths:
+  "/users/{user_id}/posts/{post_id}/comments":
+    parameters:
+    - name: user_id
+      in: path
+      required: true
+      description: User ID
+      schema:
+        type: integer
+    - name: post_id
+      in: path
+      required: true
+      description: Post ID
+      schema:
+        type: integer
+    get:
+      summary: Retrieve all comments of a post
+      tags:
+      - Comments
+      responses:
+        '200':
+          description: OK
+    post:
+      summary: Create a new comment for a post
+      tags:
+      - Comments
+      parameters: []
+      responses:
+        '201':
+          description: Created
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                text:
+                  type: string
+              required:
+              - text
+  "/users/{user_id}/posts":
+    parameters:
+    - name: user_id
+      in: path
+      required: true
+      description: User ID
+      schema:
+        type: integer
+    get:
+      summary: Retrieve all the posts of a user
+      tags:
+      - Posts
+      responses:
+        '200':
+          description: OK
+servers:
+- url: https://{defaultHost}
+  variables:
+    defaultHost:
+      default: www.example.com