jsonapi-swagger 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92c1984cded48de28c42fc2c6cea1942f17a985a485c0620941a55e8a6d8259c
-  data.tar.gz: 5ecc81a8c945a282346a0f20420be0cd047fcf715abea97986cf374285b780d1
+  metadata.gz: 5ac2522e526917a176239ca6a576b1313b935b13e5f1abd6c361a4d2650867e4
+  data.tar.gz: cba8776fff22be079490f5c450e707b2b94b08da277b58f5fa88ebbdda7bdc77
 SHA512:
-  metadata.gz: b1918de62437786e214d29396a254693899d34325d3762a20c0327bf8f340b848a36a92ae3815e16b607fbb7b07957e7d2fc7ca3b842b9f991750edcc084f6cc
-  data.tar.gz: 8f93aa0c863bc241859ca952f2d103346552af40882bbfa35d68900561a832e0af3daf4c131c361e0bced923ccf1d35e3347828fe88565bb23663cc3805ebfde
+  metadata.gz: c776c446efd665e72bbbb54595984fa37c92a250c351a4f237eebcc83f73505f63eb18574ccde7b18bc9695ac155c2d3bdd12697dd445faff56a8871c4e74994
+  data.tar.gz: ebf4e2010729433bc3b8e2af940d744b33810bf1a5579e24c0db61bf51b65c0196092110528ff9fe97132f52bee508d57029c18aa3af13897096c4607e0583db

data/README.md

@@ -2,7 +2,8 @@
 
 Generate JSONAPI Swagger Doc.
 
-[![Gem Version](https://img.shields.io/gem/v/jsonapi-swagger.svg)](https://rubygems.org/gems/jsonapi-swagger) [![GitHub license](https://img.shields.io/github/license/superiorlu/jsonapi-swagger.svg)](https://github.com/superiorlu/jsonapi-swagger/blob/master/LICENSE)
+[![Gem Version](https://img.shields.io/gem/v/jsonapi-swagger.svg)](https://rubygems.org/gems/jsonapi-swagger)
+[![GitHub license](https://img.shields.io/github/license/superiorlu/jsonapi-swagger.svg)](https://github.com/superiorlu/jsonapi-swagger/blob/master/LICENSE)
 
 [![jsonapi-swagger-4-2-9.gif](https://i.loli.net/2019/05/05/5ccebf5e782b7.gif)](https://i.loli.net/2019/05/05/5ccebf5e782b7.gif)
 
@@ -24,10 +25,40 @@ Or install it yourself as:
 
 ## Usage
 
+ 1. config jsonapi swagger
+```rb
+# config/initializers/swagger.rb
+Jsonapi::Swagger.config do |config|
+  config.use_rswag = false
+  config.version = '2.0'
+  config.info = { title: 'API V1', version: 'V1'}
+  config.file_path = 'v1/swagger.json'
+end
+```
+
+2. generate swagger.json
+
+```sh
+# gen swagger/v1/swagger.json
+bundle exec rails generate jsonapi:swagger User # UserResponse < JSONAPI::Resource
+```
+
+3. additional
+
+ use `rswag`, have to run
+
 ```sh
-rails generate jsonapi:swagger User # UserResponse < JSONAPI::Resource
+# gen swagger/v1/swagger.json
+ bundle exec rails rswag:specs:swaggerize
 ```
 
+## RoadMap
+
+- [x] immutable resources
+- [x] filter/sort resources
+- [x] mutable resources
+- [x] generate swagger.json without rswag
+
 ## Resource
 
 - [JSONAPI](https://jsonapi.org/)
@@ -36,4 +67,5 @@ rails generate jsonapi:swagger User # UserResponse < JSONAPI::Resource
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/superiorlu/jsonapi-swagger.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/superiorlu/jsonapi-swagger.

data/lib/generators/jsonapi/swagger/swagger_generator.rb

@@ -4,15 +4,54 @@ module Jsonapi
     source_root File.expand_path('templates', __dir__)
 
     def create_swagger_file
-      swagger_file = File.join(
+      if Jsonapi::Swagger.use_rswag
+        template 'swagger.rb.erb', spec_file
+      else
+        template 'swagger.json.erb', json_file
+      end
+    end
+
+    private
+
+    def doc
+      @doc ||= swagger_json.parse_doc
+    end
+
+    def spec_file
+      @spec_file ||= File.join(
         'spec/requests',
         class_path,
         spec_file_name
       )
-      template 'swagger.rb.erb', swagger_file
     end
 
-    private
+    def json_file
+      @json_file ||= File.join(
+        'swagger',
+        class_path,
+        swagger_file_path
+      )
+    end
+
+    def swagger_version
+      Jsonapi::Swagger.version
+    end
+
+    def swagger_info
+      JSON.pretty_generate(Jsonapi::Swagger.info)
+    end
+
+    def swagger_base_path
+      Jsonapi::Swagger.base_path
+    end
+
+    def swagger_file_path
+      Jsonapi::Swagger.file_path
+    end
+
+    def swagger_json
+      @swagger_json ||= Jsonapi::Swagger::Json.new(json_file)
+    end
 
     def spec_file_name
       "#{file_name.downcase.pluralize}_spec.rb"
@@ -38,6 +77,10 @@ module Jsonapi
       t(:sortable_fields) + ': (-)' + sortable_fields.join(',')
     end
 
+    def ori_sortable_fields_desc
+      tt(:sortable_fields) + ': (-)' + sortable_fields.join(',')
+    end
+
     def model_klass
       model_class_name.safe_constantize
     end
@@ -70,10 +113,11 @@ module Jsonapi
       resource_klass.filters
     end
 
-    def columns_with_comment
+    def columns_with_comment(need_encoding: true)
       @columns_with_comment ||= {}.tap do |clos|
         model_klass.columns.each do |col|
-          clos[col.name.to_sym] = { type: swagger_type(col), items_type: col.type, is_array: col.array,  nullable: col.null, comment: safe_encode(col.comment) }
+          clos[col.name.to_sym] = { type: swagger_type(col), items_type: col.type, is_array: col.array,  nullable: col.null, comment: col.comment }
+          clos[col.name.to_sym][:comment] = safe_encode(col.comment) if need_encoding
         end
       end
     end
@@ -89,10 +133,14 @@ module Jsonapi
     end
 
     def t(key, options={})
+      content = tt(key, options)
+      safe_encode(content)
+    end
+
+    def tt(key, options={})
       options[:scope] = :jsonapi_swagger
       options[:default] = key.to_s.humanize
-      content = I18n.t(key, options)
-      safe_encode(content)
+      I18n.t(key, options)
     end
 
     def safe_encode(content)

data/lib/generators/jsonapi/swagger/templates/swagger.json.erb

@@ -0,0 +1,319 @@
+{
+  "swagger": "<%= swagger_version %>",
+  "info": <%= swagger_info %>,
+  "basePath" : "<%= swagger_base_path %>",
+  <%-
+    def list_resource_parameters
+      [].tap do |parameters|
+        parameters << { name: 'page[number]', in: :query, type: :string, description: tt(:page_num), required: false }
+        parameters << { name: 'page[size]', in: :query, type: :string, description: tt(:page_size), required: false }
+        if sortable_fields.present?
+          parameters << { name: 'sort', in: :query, type: :string, description: ori_sortable_fields_desc, required: false }
+        end
+        if relationships.present?
+          parameters << { name: :include, in: :query, type: :string, description: tt(:include_related_data), required: false }
+        end
+        filters.each do |filter_attr, filter_config|
+          parameters << { name: :"filter[#{filter_attr}]", in: :query, type: :string, description: tt(:filter_field), required: false}
+        end
+        parameters << { name: :"fields[#{route_resouces}]", in: :query, type: :string, description: tt(:display_field), required: false }
+        relationships.each_value do |relation|
+          parameters << { name: :"fields[#{relation.class_name.tableize}]", in: :query, type: :string, description: tt(:display_field), required: false }
+        end
+      end
+    end
+
+    def show_resource_parameters
+      [].tap do |parameters|
+        parameters << { name: :id, in: :path, type: :integer, description: 'ID', required: true }
+        if relationships.present?
+          parameters << { name: :include, in: :query, type: :string, description: tt(:include_related_data), required: false }
+        end
+        parameters << { name: :"fields[#{route_resouces}]", in: :query, type: :string, description: tt(:display_field), required: false }
+        relationships.each_value do |relation|
+          parameters << { name: :"fields[#{relation.class_name.tableize}]", in: :query, type: :string, description: tt(:display_field), required: false }
+        end
+      end
+    end
+
+    def create_resource_parameters
+      parameters = {
+        name: :data,
+        in: :body,
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              type: { type: :string, default: route_resouces },
+              attributes: {
+                type: :object,
+                properties: properties(attrs: creatable_fields)
+              }
+            }
+          },
+        },
+        description: tt(:request_body)
+     }
+     parameters[:properties][:data][:properties][:relationships] ||= {}
+     parameters[:properties][:data][:properties][:relationships] = { type: :object, properties: create_relationships_properties }
+     parameters
+    end
+
+    def patch_resource_parameters
+      patch_parameters =  create_resource_parameters.dup
+      patch_parameters[:properties][:data][:properties][:id] ||= {}
+      patch_parameters[:properties][:data][:properties][:id].merge!({ type: :integer, description: 'ID' })
+      parameters = [{ name: :id, in: :path, type: :integer, description: 'ID', required: true }]
+      parameters << patch_parameters
+      parameters
+    end
+
+    def delete_resource_parameters
+      [{ name: :id, in: :path, type: :integer, description: 'ID', required: true }]
+    end
+
+    def properties(attrs: [])
+      Hash.new{|h, k| h[k] = {}} .tap do |props|
+        attrs.each do |attr|
+         columns = columns_with_comment(need_encoding: false)
+          props[attr][:type] = columns[attr][:type]
+          props[attr][:items] = { type: columns[attr][:items_type] } if columns[attr][:is_array]
+          props[attr][:'x-nullable'] = columns[attr][:nullable]
+          props[attr][:description] = columns[attr][:comment]
+        end
+      end
+    end
+
+    def relationships_properties
+      {}.tap do |relat_props|
+        relationships.each do |relation_name, relation|
+          relation_name_camelize = relation_name.to_s.camelize
+            relat_props[relation_name] = {
+              type: :object,
+              properties: {
+              links: {
+                type: :object,
+                properties: {
+                  self: { type: :string, description:  tt(:associate_list_link, model: relation_name_camelize) },
+                  related: { type: :string, description: tt(:related_link, model: relation_name_camelize) },
+                },
+                description: tt(:related_link, model: relation_name_camelize)
+              },
+            },
+            description: tt(:related_model, model: relation_name_camelize)
+          }
+        end
+      end
+    end
+
+    def create_relationships_properties
+      {}.tap do |relat_props|
+        relationships.each do |relation_name, relation|
+          relation_name_camelize = relation_name.to_s.camelize
+          relat_props[relation_name] = {
+            type: :object,
+            properties: {
+              data: {
+                type: :array,
+                items: {
+                  type: :object,
+                  properties: {
+                    type: { type: :string, default: relation.table_name },
+                    id: { type: :string, description: "#{relation_name_camelize} ID" },
+                  },
+                },
+                description: tt(:related_ids, model: relation_name_camelize)
+              }
+            },
+            description: tt(:related_ids, model: relation_name_camelize)
+          }
+          if relation.belongs_to?
+            relat_props[relation_name][:properties][:data] = {
+              type: :object,
+              properties: {
+                type: { type: :string, default: relation.table_name },
+                id: { type: :string, description: "#{relation_name_camelize} ID" },
+              },
+              description: tt(:related_id, model: relation_name_camelize)
+            }
+          end
+        end
+      end
+    end
+
+    def list_resource_responses
+      {
+        '200' => {
+          description: tt(:get_list),
+          schema: {
+            type: :object,
+            properties: {
+              data: {
+                type: :array,
+                items: {
+                  type: :object,
+                  properties: {
+                    id: { type: :string, description: 'ID'},
+                    links: {
+                      type: :object,
+                      properties: {
+                      self: { type: :string, description: tt(:detail_link) },
+                    },
+                    description: tt(:detail_link)
+                  },
+                  attributes: {
+                    type: :object,
+                    properties: properties(attrs: attributes.each_key),
+                    description: tt(:attributes)
+                  },
+                  relationships: {
+                    type: :object,
+                    properties: relationships_properties,
+                    description: tt(:associate_data)
+                  }
+              },
+            },
+            description: tt(:data)
+            },
+            meta: {
+              type: :object,
+              properties: {
+                record_count: { type: :integer, description: tt(:record_count)},
+                page_count: { type: :integer, description: tt(:page_count)},
+              },
+              description: tt(:meta)
+            },
+            links: {
+              type: :object,
+              properties: {
+                first: { type: :string, description: tt(:first_page_link) },
+                next: { type: :string, description: tt(:next_page_link) },
+                last: { type: :string, description: tt(:last_page_link) },
+              },
+              description: tt(:page_links) },
+          },
+          required: [:data]
+          }
+        }
+      }
+    end
+
+    def show_resource_responses
+      {
+        '200' => {
+          description: tt(:get_detail),
+          schema: show_resource_schema
+        }
+      }
+    end
+
+    def create_resource_responses
+      {
+        '201' => {
+          description: tt(:create),
+          schema: show_resource_schema
+        }
+      }
+    end
+
+    def delete_resource_responses
+      {
+        '204' => { description: tt(:delete) }
+      }
+    end
+
+    def show_resource_schema
+      {
+        type: :object,
+        properties: {
+          data: {
+            type: :object,
+            properties: {
+              id: { type: :string, description: 'ID'},
+              type: { type: :string, description: 'Type'},
+              links: {
+                type: :object,
+                properties: {
+                  self: { type: :string, description: tt(:detail_link) },
+                },
+                description: tt(:detail_link)
+              },
+              attributes: {
+                type: :object,
+                properties: properties(attrs: attributes.each_key),
+                description: tt(:attributes)
+              },
+              relationships: {
+                type: :object,
+                properties: relationships_properties,
+                description: tt(:associate_data)
+              }
+            },
+            description: tt(:data)
+          }
+        },
+        required: [:data]
+      }
+    end
+
+    doc['paths']["/#{route_resouces}"] = {
+      get: {
+        summary: "#{route_resouces} #{tt(:list)}",
+        tags: [route_resouces],
+        produces: ['application/vnd.api+json'],
+        parameters: list_resource_parameters,
+        responses: list_resource_responses
+      }
+    }
+
+    doc['paths']["/#{route_resouces}/{id}"] = {
+      get: {
+        summary: "#{route_resouces} #{tt(:detail)}",
+        tags: [route_resouces],
+        produces: ['application/vnd.api+json'],
+        parameters: show_resource_parameters,
+        responses: show_resource_responses
+      }
+    }
+
+if resource_klass.mutable?
+  doc['paths']["/#{route_resouces}"].merge!({
+    post: {
+      summary: "#{route_resouces} #{tt(:create)}",
+      tags: [route_resouces],
+      consumes: ['application/vnd.api+json'],
+      produces: ['application/vnd.api+json'],
+      parameters: [create_resource_parameters],
+      responses: create_resource_responses
+    }
+  })
+
+  doc['paths']["/#{route_resouces}/{id}"].merge!({
+    patch: {
+      summary: "#{route_resouces} #{tt(:patch)}",
+      tags: [route_resouces],
+      consumes: ['application/vnd.api+json'],
+      produces: ['application/vnd.api+json'],
+      parameters: patch_resource_parameters,
+      responses: show_resource_responses
+    }
+  })
+
+  doc['paths']["/#{route_resouces}/{id}"].merge!({
+    delete: {
+      summary: "#{route_resouces} #{tt(:delete)}",
+      tags: [route_resouces],
+      produces: ['application/vnd.api+json'],
+      parameters: delete_resource_parameters,
+      responses: delete_resource_responses
+    }
+  })
+else
+  doc['paths']["/#{route_resouces}"].delete(:post)
+  doc['paths']["/#{route_resouces}/{id}"].delete(:patch)
+  doc['paths']["/#{route_resouces}/{id}"].delete(:delete)
+end
+-%>
+  "paths": <%= JSON.pretty_generate(doc['paths'] ) %>
+}

data/lib/generators/jsonapi/swagger/templates/swagger.rb.erb

@@ -3,7 +3,11 @@ RSpec.describe '<%= resouces_name %>', type: :request do
   let(:include) {''} #see https://github.com/domaindrivendev/rswag/issues/188
 
   before(:each) do
+  <% if defined?(FactoryBot) -%>
     @<%= model_name %> = create :<%= model_name %>
+  <% else -%>
+    @<%= model_name %> = <%= model_class_name %>.create
+  <% end -%>
   end
 
   path '/<%= route_resouces %>' do

data/lib/i18n/en.yml

@@ -1,6 +1,7 @@
 en:
   jsonapi_swagger:
     page_num: 'Page Number'
+    page_size: 'Page Size'
     include_related_data: 'Include Related Data'
     sortable_fields: 'Sortable Fields'
     display_field: 'Display Field'

data/lib/i18n/zh-CN.yml

@@ -1,6 +1,7 @@
 zh-CN:
   jsonapi_swagger:
     page_num: '页码'
+    page_size: '每页条数'
     include_related_data: '包含关联数据'
     sortable_fields: '排序字段'
     display_field: '显示字段'

data/lib/jsonapi/swagger.rb

@@ -2,9 +2,38 @@
 
 require 'jsonapi/swagger/version'
 require 'jsonapi/swagger/railtie' if defined?(Rails)
+require 'jsonapi/swagger/json'
 
 module Jsonapi
   module Swagger
     class Error < StandardError; end
+
+    class << self
+      attr_accessor :version, :info, :file_path, :base_path, :use_rswag
+
+      def config
+        yield self
+      end
+
+      def version
+        @version ||= '2.0'
+      end
+
+      def info
+        @info ||= { title: 'API V1', version: 'V1' }
+      end
+
+      def file_path
+        @file_path ||= 'v1/swagger.json'
+      end
+
+      def base_path
+        @base_path
+      end
+
+      def use_rswag
+        @use_rswag ||= false
+      end
+    end
   end
 end

data/lib/jsonapi/swagger/json.rb

@@ -0,0 +1,31 @@
+module Jsonapi
+  module Swagger
+    class Json
+
+      attr_accessor :path
+
+      def initialize(path = 'swagger/v1/swagger.json')
+        @path = path
+      end
+
+      def parse_doc
+        @doc ||= JSON.parse(load) rescue Hash.new{ |h, k| h[k]= {} }
+      end
+
+      def base_path
+        Jsonapi::Swagger.base_path
+      end
+
+      def load
+        @data ||= if File.exist?(path)
+                  IO.read(path)
+                else
+                  puts "create swagger.json in #{path}"
+                  '{}'
+                end
+      end
+
+
+    end
+  end
+end

data/lib/jsonapi/swagger/version.rb

@@ -2,6 +2,6 @@
 
 module Jsonapi
   module Swagger
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-swagger
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - YingRui Lu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-08 00:00:00.000000000 Z
+date: 2019-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -59,7 +59,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -76,17 +76,18 @@ files:
 - README.md
 - lib/generators/jsonapi/swagger/USAGE
 - lib/generators/jsonapi/swagger/swagger_generator.rb
+- lib/generators/jsonapi/swagger/templates/swagger.json.erb
 - lib/generators/jsonapi/swagger/templates/swagger.rb.erb
 - lib/i18n/en.yml
 - lib/i18n/zh-CN.yml
 - lib/jsonapi/swagger.rb
+- lib/jsonapi/swagger/json.rb
 - lib/jsonapi/swagger/railtie.rb
 - lib/jsonapi/swagger/version.rb
 homepage: https://github.com/superiorlu/jsonapi-swagger
 licenses:
 - MIT
-metadata:
-  allowed_push_host: https://rubygems.org
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths: