oas_rails 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eb785a5d2e4c2bf2ab00931fded8770c0f162b21dee065c9770f159f0ddd86d
-  data.tar.gz: 2ce8852c11a5f9d2e6263bc7f067e12e83029a9f87aeefc6912884f0c5912408
+  metadata.gz: 8ef226b2db87f8eedd0553f817ec31387484ddc848130e231b4878565770407a
+  data.tar.gz: b6805acaa691160d12b40362e2365d94dd0e8e9c4a658bba4ee8543ed6ffdc37
 SHA512:
-  metadata.gz: 8a869a622b0cc9dc8710e665b70732d9993b16dce77ebae9529c73be10e794cb5a1820213dcca99380d05e810df04e00eb2ba6e11c5457c0ec76b9b82c7a740e
-  data.tar.gz: 515c5e3a66de74241ec303dfe276104d86bee128d0cc790d40a3dcff8534dcb3dbf7d283201bffd0b4089d30b03fc90f567d512714663f6dd0d39535bae0ae92
+  metadata.gz: 91e1747ebe615671cde122bd7c569962a842ad436e7bd27bc1f532ce776fad76356f780e66aeb44ff483b431ec70d696adff18497ef0a6903bb3d7c3704af1d5
+  data.tar.gz: 10313de49b83276af04d3b6085685b377464650e06e1a5166cc65c540968218c47063caec6f033b29bb49c4691385a93f03d9cb6725303a227d171ce497eb784

data/README.md

@@ -1,7 +1,12 @@
+![Gem Version](https://img.shields.io/gem/v/oas_rails)
+![GitHub License](https://img.shields.io/github/license/a-chacon/oas_rails)
+
 # Open API Specification For Rails
 
 OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
 
+![Screenshot](https://raw.githubusercontent.com/a-chacon/oas_rails/0cfc9abb5be85e6bb3fc4669e29372be8f80a276/oas_rails_ui.png)
+
 ## Related Projects
 
 - **[ApiPie](https://github.com/Apipie/apipie-rails)**: Doesn't support OAS 3.1, requires learning a DSL, lacks a nice UI
@@ -64,7 +69,8 @@ Then complete the created file with your data.
 
 Almost every description in an OAS file supports simple markdown. The following tags are available for documenting your endpoints:
 
-### @summary
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@summary</summary>
 
 **Structure**: `@summary text`
 
@@ -73,7 +79,10 @@ Used to add a summary to the endpoint. It replaces the default summary/title of
 **Example**:
 `# @summary This endpoint creates a User`
 
-### @parameter
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@parameter</summary>
 
 **Structure**: `@parameter name(position) [type] text`
 
@@ -83,7 +92,10 @@ Represents a parameter for the endpoint. The position can be: `header`, `path`,
 `# @parameter page(query) [Integer] The page number.`
 `# @parameter slug(path) [String!] Slug of the Project.`
 
-### @request_body
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@request_body</summary>
 
 **Structure**: `@request_body text [type] structure`
 
@@ -92,7 +104,10 @@ Documents the request body needed by the endpoint. The structure is optional if
 **Example**:
 `# @request_body The user to be created [Hash] {user: {name: String, age: Integer, password: String}}`
 
-### @request_body_example
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@request_body_example</summary>
 
 **Structure**: `@request_body_example text [type] structure`
 
@@ -101,7 +116,10 @@ Adds examples to the provided request body.
 **Example**:
 `# @request_body_example A complete User. [Hash] {user: {name: 'Luis', age: 30, password: 'MyWeakPassword123'}}`
 
-### @response
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@response</summary>
 
 **Structure**: `@response text(code) [type] structure`
 
@@ -110,7 +128,10 @@ Documents the responses of the endpoint and overrides the default responses foun
 **Example**:
 `# @response User not found by the provided Id(404) [Hash] {success: Boolean, message: String}`
 
-### @tag
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@tag</summary>
 
 **Structure**: `@tag text`
 
@@ -119,8 +140,87 @@ Tags your endpoints. You can complete the tag documentation in the initializer f
 **Example**:
 `# @tag Users`
 
+</details>
+
 You can use these tags in your controller methods to enhance the automatically generated documentation. Remember to use markdown formatting in your descriptions for better readability in the generated OAS document.
 
+### Example of documented endpoints
+
+```ruby
+class UsersController < ApplicationController
+  before_action :set_user, only: %i[show update destroy]
+
+  # @summary Returns a list of Users.
+  #
+  # @parameter offset(query) [Integer]  Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
+  # @parameter status(query) [Array<String>]   Filter by status. (e.g. status[]=inactive&status[]=deleted).
+  # @parameter X-front(header) [String] Header for identify the front.
+  def index
+    @users = User.all
+  end
+
+  # @summary Get a user by id.
+  #
+  # This method show a User by ID. The id must exist of other way it will be returning a **`404`**.
+  #
+  # @parameter id(path) [Integer] Used for identify the user.
+  # @response Requested User(200) [Hash] {user: {name: String, email: String, created_at: DateTime }}
+  # @response User not found by the provided Id(404) [Hash] {success: Boolean, message: String}
+  # @response You don't have the right permission for access to this resource(403) [Hash] {success: Boolean, message: String}
+  def show
+    render json: @user
+  end
+
+  # @summary Create a User
+  #
+  # @request_body The user to be created. At least include an `email`. [User!]
+  # @request_body_example basic user [Hash] {user: {name: "Luis", email: "luis@gmail.ocom"}}
+  def create
+    @user = User.new(user_params)
+
+    if @user.save
+      render json: @user, status: :created
+    else
+      render json: { success: false, errors: @user.errors }, status: :unprocessable_entity
+    end
+  end
+
+  # A `user` can be updated with this method
+  # - There is no option
+  # - It must work
+  # @tags users, update
+  # @request_body User to be created [Hash] {user: { name: String, email: String, age: Integer}}
+  # @request_body_example Update user [Hash] {user: {name: "Luis", email: "luis@gmail.com"}}
+  # @request_body_example Complete User [Hash] {user: {name: "Luis", email: "luis@gmail.com", age: 21}}
+  def update
+    if @user.update(user_params)
+      render json: @user
+    else
+      render json: @user.errors, status: :unprocessable_entity
+    end
+  end
+
+  # @summary Delete a User
+  # Delete a user and his associated data.
+  def destroy
+    @user.destroy!
+    redirect_to users_url, notice: 'User was successfully destroyed.', status: :see_other
+  end
+
+  private
+
+  # Use callbacks to share common setup or constraints between actions.
+  def set_user
+    @user = User.find(params[:id])
+  end
+
+  # Only allow a list of trusted parameters through.
+  def user_params
+    params.require(:user).permit(:name, :email)
+  end
+end
+```
+
 ## Contributing
 
 Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

data/app/views/layouts/oas_rails/application.html.erb

@@ -7,8 +7,6 @@
     <meta charset="utf-8">
     <!-- Important: rapi-doc uses utf8 characters -->
     <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
-
-    <%= stylesheet_link_tag "oas_rails/application", media: "all" %>
   </head>
   <body>
 

data/lib/generators/oas_rails/config/templates/oas_rails_initializer.rb

@@ -44,6 +44,7 @@ OasRails.configure do |config|
   config.tags = [{ name: "Users", description: "Manage the `amazing` Users table." }]
 
   # config.default_tags_from = :namespace # Could be: :namespace or :controller
-  # config.request_body_automatically = true # Try to get request body for create and update methos based on the controller name.
+  # config.autodiscover_request_body = true # Try to get request body for create and update methods based on the controller name.
   # config.autodiscover_responses = true # Looks for renders in your source code and try to generate the responses.
+  # config.api_path = "/" # set this config if your api is in a different namespace other than /
 end

data/lib/oas_rails/configuration.rb

@@ -1,6 +1,6 @@
 module OasRails
   class Configuration
-    attr_accessor :info, :default_tags_from, :request_body_automatically, :autodiscover_responses
+    attr_accessor :info, :default_tags_from, :autodiscover_request_body, :autodiscover_responses, :api_path
     attr_reader :servers, :tags
 
     def initialize(**kwargs)
@@ -9,8 +9,9 @@ module OasRails
       @tags = []
       @swagger_version = '3.1.0'
       @default_tags_from = "namespace"
-      @request_body_automatically = true
+      @autodiscover_request_body = true
       @autodiscover_responses = true
+      @api_path = "/"
     end
 
     def default_servers

data/lib/oas_rails/operation.rb

@@ -89,7 +89,7 @@ module OasRails
 
       def extract_request_body(oas_route:)
         tag_request_body = oas_route.docstring.tags(:request_body).first
-        if tag_request_body.nil? && OasRails.config.request_body_automatically
+        if tag_request_body.nil? && OasRails.config.autodiscover_request_body
           oas_route.detect_request_body if %w[create update].include? oas_route.method
         elsif !tag_request_body.nil?
           RequestBody.from_tags(tag: tag_request_body, examples_tags: oas_route.docstring.tags(:request_body_example))

data/lib/oas_rails/route_extractor.rb

@@ -79,6 +79,7 @@ module OasRails
         return false if route.defaults[:controller].nil?
         return false if RAILS_DEFAULT_CONTROLLERS.any? { |default| route.defaults[:controller].start_with?(default) }
         return false if RAILS_DEFAULT_PATHS.any? { |path| route.path.spec.to_s.include?(path) }
+        return false unless route.path.spec.to_s.start_with?(OasRails.config.api_path)
 
         true
       end

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - a-chacon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-27 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: esquema