Merge pull request #12 from zunairkhan811/api-documentation

 Create API Documentation

.rubocop.yml

@@ -26,7 +26,7 @@ Metrics/ClassLength:
   Max: 150
 Metrics/BlockLength:
   AllowedMethods: ['describe']
-  Max: 30
+  Max: 50
 
 Style/Documentation:
   Enabled: false

Gemfile

@@ -74,4 +74,5 @@ end
 gem 'bootstrap_form', '~> 5.4'
 gem 'cancancan'
 gem 'devise', '~> 4.9'
+gem 'rswag'
 gem 'rubocop', '>= 1.0', '< 2.0'

Gemfile.lock

@@ -117,6 +117,8 @@ GEM
       actionview (>= 5.0.0)
       activesupport (>= 5.0.0)
     json (2.6.3)
+    json-schema (4.1.1)
+      addressable (>= 2.8)
     language_server-protocol (3.17.0.3)
     loofah (2.22.0)
       crass (~> 1.0.2)
@@ -219,6 +221,21 @@ GEM
       rspec-mocks (~> 3.12)
       rspec-support (~> 3.12)
     rspec-support (3.12.1)
+    rswag (2.13.0)
+      rswag-api (= 2.13.0)
+      rswag-specs (= 2.13.0)
+      rswag-ui (= 2.13.0)
+    rswag-api (2.13.0)
+      activesupport (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
+    rswag-specs (2.13.0)
+      activesupport (>= 3.1, < 7.2)
+      json-schema (>= 2.2, < 5.0)
+      railties (>= 3.1, < 7.2)
+      rspec-core (>= 2.14)
+    rswag-ui (2.13.0)
+      actionpack (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
     rubocop (1.57.2)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -291,6 +308,7 @@ DEPENDENCIES
   rails (~> 7.0.8)
   rails-controller-testing
   rspec-rails
+  rswag
   rubocop (>= 1.0, < 2.0)
   selenium-webdriver
   sprockets-rails

README.md

@@ -17,6 +17,7 @@
   - [Install](#install)
   - [Usage](#usage)
   - [Run tests](#run-tests)
+  - [Blog API](#Blog-API)
   - [👥 Authors](#authors)
 - [🔭 Future Features](#future-features)
 - [🤝 Contributing](#contributing)
@@ -58,16 +59,12 @@
 ### Key Features <a name="key-features"></a>
 
 - **[App for blog, create post, add likes and comments]**
+- **[Blog API is also created. API links are accessible at https://localhost:3000/api-docs/index.html after running server by running `rails s` command in terminal]**
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## 💻 Getting Started <a name="getting-started"></a>
 
-To get a local copy up and running, follow these steps.
-
-- clone this https://github.com/zunairkhan811/blog-app.git
-
-
 ### Prerequisites
 
 In order to run this project you need:
@@ -78,31 +75,49 @@ In order to run this project you need:
 ### Setup
 
 Clone this repository to your desired folder:
-<ul>
-<li>cd my-folder</li>
-<li>git clone https://github.com/zunairkhan811/blog-app.git</li>
-</ul>
+
+ `cd my-folder`
+
+ `git clone https://github.com/zunairkhan811/blog-app.git`
+
 
 ### Install
 
 Install this project with:
-<ul>
-<li>bundle install</li>
-</ul>
+
+`bundle install`
 
 ### Usage
 
 To run the project, execute the following command:
-<ul>
-<li>rails s</li>
-</ul>
+
+`rail s`
 
 ### Run tests
 
 <!-- To run tests, run the following command: Install through : gem install rspec -->
 
-Run: ***Not Available for now***
+Run: `rspec spec`
+
+### Blog API
+Blog API is also created:
+
+User can list all user posts through the below link
+`http://localhost:3000/api/v1/users/:user_id/user_posts `
+
+User can see the list of all comments for a posts through the below link
+`http://localhost:3000/api/v1/posts/:post_id/post_comments`
+
+User can create a comment to a post with the following Url link:
+`http://localhost:3000/api/v1/posts/:post_id/post_comments`
+
+### API Docs:
+
+API docs are created and are accessible by following steps:
+
+`Run rails s command in the terminal`
 
+`Paste this Link http://localhost:3000/api-docs/index.html in the Browser.`
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## 👥 Author <a name="author"></a>
@@ -112,7 +127,7 @@ Run: ***Not Available for now***
 
 - GitHub: [@zunairkhan811](https://github.com/zunairkhan811)
 - Twitter: [@zunairkhan811](https://twitter.com/zunairkhan811)
-- LinkedIn: [mzunairkhan](https://www.linkedin.com/in/mzunairkhan)
+- LinkedIn: [@mzunairkhan](https://www.linkedin.com/in/mzunairkhan)
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -121,7 +136,7 @@ Run: ***Not Available for now***
 ## 🔭 Future Features <a name="future-features"></a>
 
 
-- [ ] **[Data connections, Adding Validations, Creating Full Blog page App]**
+- [ ] **[Will add more features in the app]**
 
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -151,7 +166,7 @@ I would like to thank Microverse and my Code Reviewers.
 
 - **[What is Blog App?]**
 
-  - [In this project, we will creating posts, and adding likes and comments in rails framework]
+  - [In this project, we will creating users, posts, and adding likes and comments in rails framework. Blog API is also created alongwith API docs.]
 
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>

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.openapi_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 openapi_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
       resources :users do

spec/integration/blog_api_spec.rb

@@ -0,0 +1,70 @@
+require 'swagger_helper'
+
+describe 'Blog API' do
+  path '/api/v1/users/{user_id}/user_posts' do
+    get 'Retrieves posts for a user' do
+      tags 'UserPosts'
+      parameter name: :user_id, in: :path, type: :integer, description: 'ID of the user'
+      produces 'application/json'
+      response '200', 'OK' do
+        schema type: :array,
+               items: {
+                 type: :object,
+                 properties: {
+                   id: { type: :integer },
+                   title: { type: :string }
+                 }
+               },
+               required: %w[id title]
+        let(:user_id) { create(:user).id }
+        run_test!
+      end
+    end
+  end
+
+  path '/api/v1/posts/{post_id}/post_comments' do
+    get 'Retrieves comments for a post' do
+      tags 'PostComments'
+      parameter name: :post_id, in: :path, type: :integer, description: 'ID of the post'
+      produces 'application/json'
+      response '200', 'OK' do
+        schema type: :array,
+               items: {
+                 type: :object,
+                 properties: {
+                   id: { type: :integer },
+                   text: { type: :string }
+                 }
+               },
+               required: %w[id text]
+        let(:post_id) { create(:post).id }
+        run_test!
+      end
+    end
+
+    post 'Creates a comment for a post' do
+      tags 'PostComments'
+      parameter name: :post_id, in: :path, type: :integer, description: 'ID of the post'
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :comment, in: :body, schema: {
+        type: :object,
+        properties: {
+          text: { type: :string }
+        },
+        required: ['text']
+      }
+      response '201', 'Created' do
+        let(:post_id) { create(:post).id }
+        let(:comment) { { text: 'This is a comment' } }
+        run_test!
+      end
+
+      response '422', 'Unprocessable Entity' do
+        let(:post_id) { create(:post).id }
+        let(:comment) { { text: '' } }
+        run_test!
+      end
+    end
+  end
+end

spec/swagger_helper.rb

@@ -0,0 +1,44 @@
+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.openapi_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 openapi_root
+  # By default, the operations defined in spec files are added to the first
+  # document below. You can override this behavior by adding a openapi_spec tag to the
+  # the root example_group in your specs, e.g. describe '...', openapi_spec: 'v2/swagger.json'
+  config.openapi_specs = {
+    'v1/swagger.yaml' => {
+      openapi: '3.0.1',
+      info: {
+        title: 'Blog API',
+        version: 'v1',
+        description: 'This API gives shows the number of Posts created by a user
+        and also show the list of Comments and also have the ability to create comments
+        by the user in the database'
+      },
+      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 openapi_specs 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.openapi_format = :yaml
+end