swaggard 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a917d95609c038ad062ceed22c30c031f6a89e2
-  data.tar.gz: ee9e6c25500409270e09878627e7c3e3f38df912
+  metadata.gz: fb687a1c23c74e8d1e4ba9c61ee2cf721825dd5e
+  data.tar.gz: e5ce9def3e2218ab2de5aed5464cb3c58444845d
 SHA512:
-  metadata.gz: 226caeb3f072e23e7ad016bafae52017e8086d2a04cf06640c5b7ad058825595b1b21b38796af049f5c9594269238361ebd5c6ae178b3417b9ec69ec88ef0af9
-  data.tar.gz: 1fd2aee9b4ed62117a92fa389f46aa18021ec4159235bc99da513074b6eeb2f1bf6799ab9d6d42290a76317f182983bf1d680d4e5782d011354462b2e3ff8739
+  metadata.gz: e080901eb5706ca5f0a878a7c820281b0ee88a69e6f7b37f1a7b8cffc1cdee25ddbdba5778d24df0713b51d8ee035631f5aba64db68a12b6f25c2e8124d8d14c
+  data.tar.gz: 36d8dd883ecebd67b634e0cc13bac4fbae700b67eef630628d46f538d4f2be1f0332b1e72f4ff940b3fc09360df69032a0842d30b70b08f0be2f133f50528cab

data/README.md

@@ -1,41 +1,25 @@
-Swaggard
-========
+# Swaggard
 
 Swaggard is a Rails Engine that can be used to document a REST api. It does this by generating a json that is compliant with [Swagger](http://swagger.io) and displaying it using [Swagger-ui](https://github.com/wordnik/swagger-ui).
 This gem is inspired and based on [SwaggerYard](https://github.com/synctv/swagger_yard) by [Chris Trinh](https://github.com/chtrinh).
 
-Compatibility
--------------
-This table tracks the version of Swagger UI used on each Swaggard version and
-the supported rails version.
-
-Swaggard Version | Swagger UI Version | Supported Rails Versions
----------------- | -------------------| ------------------------
-0.5.0            | 2.2.8              | 4 - 5
-0.4.0            | 2.2.8              | 4
-0.3.0            | 2.1.3              | 4
-0.2.1            | 2.1.3              | 4
-0.2.0            | 2.1.3              | 4
-0.1.1            | 2.1.3              | 4
-0.1.0            | 2.1.3              | 4
-0.0.4            | 2.1.8-M1           | 4
 
-Swaggard vs SwaggerYard
------------------------
+## Compatibility
 
-The main reason this gem exists is to avoid having to write by hand some information and use what
-rails already give us ie: controllers names and methods paths.
+This table tracks the version of Swagger UI used on each Swaggard version and
+the supported rails version.
 
-And also:
-  - Bring support for Rails 4.
-  - Bring support for Swagger 2.
-  - Bring support for models (serializers).
-  - Bring support for form and body params.
-  - and more...
+Swaggard Version | Swagger UI Version  | Supported Rails Versions
+---------------- | ------------------- | ------------------------
+0.5.x            | 2.2.8               | 4 - 5
+0.4.x            | 2.2.8               | 4
+0.3.x            | 2.1.3               | 4
+0.2.x            | 2.1.3               | 4
+0.1.x            | 2.1.3               | 4
+0.0.x            | 2.1.8-M1            | 4
 
 
-Installation
-------------
+## Installation
 
 Put Swaggard in your Gemfile:
 
@@ -46,8 +30,7 @@ Install the gem with Bundler:
     bundle install
 
 
-Getting Started
------------------
+## Getting Started
 
 Place your configuration in a your rails initializers
 
@@ -74,8 +57,8 @@ Access the raw swagger json
 
 	open http://localhost:3000/swagger.json
 
-Example
--------
+
+## Example
 
 By just using Swaggard you'll get documentation for the endpoints that exist on your service:
 http method, path, path params. And grouping will be done based on the controller that holds
@@ -86,15 +69,23 @@ of the expected inputs and outputs or even change the grouping of the endpoints.
 
 Here is a example of how to use Swaggard
 
+    # config/routes.rb
+
+    resources :users, only: [] do
+      resources :posts, controller: 'users/posts', only: [:index, :create]
+    end
+
+
     # app/controllers/users/posts_controller.rb
 
-    # User posts
-    #
+    # @tag UsersPosts
     # API for creating, deleting, and listing user posts.
-    class User::PostsController < ActionController::Base
+    class Users::PostsController < ActionController::Base
 
       # Returns the list of user posts
       #
+      # @response_status 201
+      # @response_root posts
       # @response_class Array<PostSerializer>
       def index
         ...
@@ -155,10 +146,26 @@ Will generate
 ![Web UI](https://raw.githubusercontent.com/Moove-it/swaggard/master/example/web-ui.png)
 
 
-Primitive type
---------------
-When one of this types is given Swaggard will handle them directly instead of searching for
-a definition:
+## Available tags
+
+### Controllers
+
+- `@tag name` This is used to indicate under what `name` tag this controller needs to be grouped. If not provided it will use the full controller class name.
+- `@query_parameter [type] name` This is used to indicate that your action receives the `name` parameter of `type` on the query string.
+- `@body_parameter [type] name` This is used to indicate that your action receives the `name` parameter of `type` on the body.
+- `@response_class type` This is used to indicate that your action returns a response of `type`.
+- `@response_status 200` This is used to indicate the response code of your action when everything goes well.
+- `@response_root name` This is used to indicate that your action returns its response inside a root key element `name`. If not provided the root is omitted and the response its returned directly.
+- `@form_parameter`
+- `@parameter_list`
+
+### Models
+
+- `@attr [type] name` This is used to indicate that your models has an attribute `name` of `type`.
+
+## Primitives
+
+When one of these types is given Swaggard will handle them directly instead of searching for a definition:
 
 - integer
 - long
@@ -173,8 +180,8 @@ a definition:
 - password
 - hash
 
-Authentication
---------------
+
+## Authentication
 
 Swaggard supports two types of authentication: header and query.
 
@@ -189,8 +196,8 @@ You can configure it as follows:
 
 Even if you provide a authentication_value you can later change it from the ui.
 
-Access authorization
---------------
+
+## Access authorization
 
 Swaggard supports access authorization.
 
@@ -205,8 +212,7 @@ You can configure it as follows:
 If you not set `access_username`, everyone will have access to Swagger documentation.
 
 
-Additional parameters
---------------
+## Additional parameters
 
 Swaggard supports additional parameters to be sent on every request, either as a header or as part of the query.
 
@@ -221,8 +227,8 @@ type can be 'header' or 'query'.
 If value is provided then it will be used as a default.
 You can change/set the value for the parameters in the ui.
 
-Default content type
---------------
+
+## Default content type
 
 You can set default content type in Swaggard configuration as follows:
 
@@ -233,8 +239,8 @@ You can set default content type in Swaggard configuration as follows:
 
 If you set `default_content_type`, Swagger will use it in example request.
 
-Language
---------------
+
+## Language
 
 You can set the language for SwaggerUI as follows:
 
@@ -260,8 +266,8 @@ Supported values are:
 - tr
 - zh-cn
 
-Caching
---------------
+
+## Caching
 
 You can improve Swagger performance by using caching. You can enable `use_cache` in Swaggard configuration as follows:
 
@@ -274,8 +280,9 @@ If you set `use_cache` as `Rails.env.production?`, Swagger will use cache only i
 
 Note. For cache clearing you can execute `rake swaggard:clear_cache`.
 
-Documentation Scoping
----------------------
+
+## Documentation Scoping
+
 Its possible to only generate Swagger documentation for a subset of your application controllers
 to do this you just need to use the `controllers_path` config option.
 For instance to only generate documentation for the controllers under `app/controllers/api` you
@@ -290,22 +297,20 @@ need do this:
 
 The default value for `controllers_path` is `"#{Rails.root}/app/controllers/**/*.rb"`.
 
-More Information
------------------
+
+## More Information
 
 - [Swagger](http://swagger.io)
 - [Swagger-ui](https://github.com/wordnik/swagger-ui)
 - [Yard](https://github.com/lsegal/yard)
 
 
-Author
-------
+## Author
 
 [Adrian Gomez](https://github.com/adrian-gomez)
 
 
-Credits
--------
+## Credits
 
 [Chris Trinh](https://github.com/chtrinh) author of [SwaggerYard](https://github.com/synctv/swagger_yard) in which this gem is
 inspired and used a base.

data/lib/swaggard/engine.rb

@@ -1,8 +1,9 @@
 unless Rails::Application.instance_methods.include?(:assets_manifest)
   warn <<-END
-[Swaggard] It seems you are using an api only rails setup but swaggard
-[Swaggard] neeeds sprockets in order to work. This might have undesired side effects,
-[Swaggard] if thats not the case you can ignore this warning.
+[Swaggard] It seems you are using an api only rails setup, but swaggard
+[Swaggard] neeeds sprockets in order to work so its going to require it.
+[Swaggard] This might have undesired side effects, if thats not  the case
+[Swaggard] you can ignore this warning.
   END
   require 'sprockets/railtie'
 end

data/lib/swaggard/swagger/operation.rb

@@ -5,7 +5,6 @@ require_relative 'parameters/path'
 require_relative 'parameters/query'
 
 require_relative 'response'
-require_relative 'default_response'
 
 module Swaggard
   module Swagger
@@ -37,7 +36,11 @@ module Swaggard
           when 'parameter_list'
             @parameters << Parameters::List.new(value)
           when 'response_class'
-            @responses << Response.new(200, value)
+            success_response.response_class = value
+          when 'response_status'
+            success_response.status_code = value
+          when 'response_root'
+            success_response.response_root = value
           end
         end
 
@@ -45,7 +48,7 @@ module Swaggard
 
         @parameters.sort_by { |parameter| parameter.name }
 
-        @responses << DefaultResponse.new unless @responses.any?
+        @responses << success_response
       end
 
       def valid?
@@ -69,11 +72,17 @@ module Swaggard
       end
 
       def definitions
-        @body_parameter ? [@body_parameter.definition] : []
+        @responses.map(&:definition).compact.tap do |definitions|
+          definitions << @body_parameter.definition if @body_parameter
+        end
       end
 
       private
 
+      def success_response
+        @success_response ||= Response.new("#{@tag.controller_class.to_s}.#{@name}")
+      end
+
       def body_parameter
         return @body_parameter if @body_parameter
 
@@ -98,4 +107,4 @@ module Swaggard
 
     end
   end
-end
+end

data/lib/swaggard/swagger/parameters/body.rb

@@ -66,4 +66,4 @@ module Swaggard
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/property.rb

@@ -20,4 +20,4 @@ module Swaggard
 
     end
   end
-end
+end

data/lib/swaggard/swagger/response.rb

@@ -2,52 +2,87 @@ module Swaggard
   module Swagger
     class Response
 
-      PRIMITIVE_TYPES = %w[number string integer float boolean]
+      DEFAULT_STATUS_CODE = 'default'
+      DEFAULT_DESCRIPTION = 'successful operation'
+      PRIMITIVE_TYPES = %w[integer long float double string byte binary boolean date date-time password hash]
 
-      attr_reader :status_code
+      attr_writer :status_code, :description
 
-      def initialize(status_code, value)
-        @status_code = status_code
-        parse(value)
+      def initialize(operation_name)
+        @operation_name = operation_name
+        @response_model = ResponseModel.new
+      end
+
+      def definition
+        return unless @response_root.present?
+
+        @definition ||= Definition.new("#{@operation_name}_response").tap do |definition|
+          definition.add_property(@response_model)
+        end
+      end
+
+      def status_code
+        @status_code || DEFAULT_STATUS_CODE
+      end
+
+      def response_class=(value)
+        @response_model.parse(value)
+      end
+
+      def response_root=(root)
+        @response_root = root
+        @response_model.id = root
+      end
+
+      def description
+        @description || DEFAULT_DESCRIPTION
       end
 
       def to_doc
-        {
-          'description' => '',
-          'schema'      => response_model
-        }
+        { 'description' => description }.tap do |doc|
+          schema = if @response_root.present?
+                     { '$ref' => "#/definitions/#{definition.id}" }
+                   elsif @response_model.response_class.present?
+                     @response_model.to_doc
+                   end
+
+          doc.merge!('schema' => schema) if schema
+        end
       end
 
       private
 
-      def parse(value)
-        @is_array_response = value =~ /Array/
-        @response_class = if @is_array_response
-                            value.match(/^Array<(.*)>$/)[1]
-                          else
-                            value
-                          end
-      end
-
-      def response_model
-        if @is_array_response
-          {
-            'type'  => 'array',
-            'items' => response_class_type
-          }
-        else
-          response_class_type
+      class ResponseModel
+        attr_accessor :id, :response_class
+
+        def parse(value)
+          @is_array_response = value =~ /Array/
+          @response_class = if @is_array_response
+                              value.match(/^Array<(.*)>$/)[1]
+                            else
+                              value
+                            end
         end
-      end
 
-      def response_class_type
-        if PRIMITIVE_TYPES.include?(@response_class)
-          { 'type' => @response_class }
-        else
-          { '$ref' => "#/definitions/#@response_class" }
+        def to_doc
+          if @is_array_response
+            {
+              'type'  => 'array',
+              'items' => response_class_type
+            }
+          else
+            response_class_type
+          end
         end
-      end
 
+        def response_class_type
+          if PRIMITIVE_TYPES.include?(@response_class)
+            { 'type' => @response_class }
+          else
+            { '$ref' => "#/definitions/#@response_class" }
+          end
+        end
+      end
     end
   end
-end
+end

data/lib/swaggard/version.rb

@@ -1,5 +1,5 @@
 module Swaggard
 
-  VERSION = '0.5.1'
+  VERSION = '0.5.2'
 
 end

data/lib/swaggard.rb

@@ -28,6 +28,8 @@ module Swaggard
       ::YARD::Tags::Library.define_tag('Body parameter',  :body_parameter)
       ::YARD::Tags::Library.define_tag('Parameter list',  :parameter_list)
       ::YARD::Tags::Library.define_tag('Response class',  :response_class)
+      ::YARD::Tags::Library.define_tag('Response Root',  :response_root)
+      ::YARD::Tags::Library.define_tag('Response Status',  :response_status)
     end
 
     def get_doc(host)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swaggard
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Adrian Gomez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-18 00:00:00.000000000 Z
+date: 2017-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -167,7 +167,6 @@ files:
 - lib/swaggard/parsers/controllers.rb
 - lib/swaggard/parsers/models.rb
 - lib/swaggard/parsers/routes.rb
-- lib/swaggard/swagger/default_response.rb
 - lib/swaggard/swagger/definition.rb
 - lib/swaggard/swagger/operation.rb
 - lib/swaggard/swagger/parameters/base.rb

data/lib/swaggard/swagger/default_response.rb

@@ -1,17 +0,0 @@
-module Swaggard
-  module Swagger
-    class DefaultResponse
-
-      def status_code
-        'default'
-      end
-
-      def to_doc
-        {
-          'description' => 'successful operation'
-        }
-      end
-
-    end
-  end
-end