jsapi 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4326454795353f4fc3d2513d4b58b5d42df113665fb3e7b197e2aac0917de794
-  data.tar.gz: 3f25ce60031f26bb76b3a4dbebd7cf9cd333ae928bc59d12aee46d215206dcc2
+  metadata.gz: fbf64d8068afe39168667e9f907654d308ab933d7688c1a10a7c6341f66a13d5
+  data.tar.gz: 006af1f3b5fec80a643c7dab1bdc82917428c355930c434302df465177235359
 SHA512:
-  metadata.gz: 1f0304f56a303c1e2658ddaf31a40c0e3d6ad4584094896cc6eeb9fb40c919e91f45fffa9bc47a0f8096426eadcd301987de313f5145b779974d874f89988a4e
-  data.tar.gz: b2255d64dc7c9e8b05c639a2e62fbc7e33dc71074d3284aedd5788de4da8951c9aebc00c8589a4240bcf450f17ba8090696e96ea5a1259e3c81004fc3b2e9776
+  metadata.gz: 04a02c4e688e8c02cf7cbb4ee66356bdcb570fa9ff89a8ba3303d52f4713d7bc5c8bbbddafd22b3871d3de960e7606f25dd9496d39731f0fa0e095ffa53688a0
+  data.tar.gz: 5099312a76a600aed362733b23bf4e358ba18b3f5a9f060258cb5aabed3caecab8d28afd9034844ce8619adf5a811f418c7fc19b28f67738392d0ec8becc659e

data/lib/jsapi/controller/error_result.rb

@@ -10,8 +10,7 @@ module Jsapi
 
       delegate :message, :to_s, to: :@exception
 
-      # Creates a new instance to produce an error response with the given
-      # HTTP status code.
+      # Creates a new instance to produce an error response with the given HTTP status code.
       def initialize(exception, status:)
         @exception = exception
         @status = status

data/lib/jsapi/controller/methods.rb

@@ -3,8 +3,8 @@
 module Jsapi
   module Controller
     module Methods
-      # Returns the Meta::Definitions instance associated with the controller class.
-      # This method can be used to create an OpenAPI document, for example:
+      # Returns the Meta::Definitions instance associated with the controller class. In
+      # particular, this method can be used to create an OpenAPI document, for example:
       #
       #   render(json: api_definitions.openapi_document)
       #
@@ -12,10 +12,10 @@ module Jsapi
         self.class.api_definitions
       end
 
-      # Performs an API operation by calling the given block. The request parameters
-      # are passed as an instance of the operation's model class to the block. The
-      # object returned by the block is implicitly rendered according to the
-      # appropriate +response+ specification.
+      # Performs an API operation by calling the given block. The request parameters are
+      # passed as an instance of the operation's model class to the block. The object
+      # returned by the block is implicitly rendered according to the appropriate
+      # +response+ specification.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -23,10 +23,9 @@ module Jsapi
       #
       # +operation_name+ can be +nil+ if the controller handles one operation only.
       #
-      # If +strong+ is +true+, parameters that can be mapped are accepted only.
-      # That means that the model passed to the block is invalid if there are any
-      # request parameters that cannot be mapped to a parameter or a request body
-      # property of the operation.
+      # If +strong+ is +true+, parameters that can be mapped are accepted only. That means
+      # that the model passed to the block is invalid if there are any request parameters
+      # that can't be mapped to a parameter or a request body property of the operation.
       #
       def api_operation(operation_name = nil, status: nil, strong: false, &block)
         _perform_api_operation(
@@ -37,8 +36,8 @@ module Jsapi
         )
       end
 
-      # Like +api_operation+, except that a ParametersInvalid exception is raised
-      # if the request parameters are invalid.
+      # Like +api_operation+, except that a ParametersInvalid exception is raised on
+      # invalid request parameters.
       #
       #   api_operation!('foo') do |api_params|
       #     # ...
@@ -59,13 +58,11 @@ module Jsapi
       #
       # +operation_name+ can be +nil+ if the controller handles one operation only.
       #
-      # If +strong+ is +true+, parameters that can be mapped are accepted only.
-      # That means that the model returned is invalid if there are any request
-      # parameters that cannot be mapped to a parameter or a request body property
-      # of the operation.
+      # If +strong+ is +true+, parameters that can be mapped are accepted only. That means
+      # that the model returned is invalid if there are any request parameters that can't be
+      # mapped to a parameter or a request body property of the operation.
       #
       # Note that each call of +api_params+ returns a newly created instance.
-      #
       def api_params(operation_name = nil, strong: false)
         definitions = api_definitions
         _api_params(
@@ -75,8 +72,8 @@ module Jsapi
         )
       end
 
-      # Returns a Response to serialize the JSON representation of +result+ according
-      # to the appropriate +response+ specification.
+      # Returns a Response to serialize the JSON representation of +result+ according to the
+      # appropriate +response+ specification.
       #
       #   render(json: api_response(bar, 'foo', status: 200))
       #

data/lib/jsapi/controller/parameters.rb

@@ -8,13 +8,12 @@ module Jsapi
 
       attr_reader :raw_attributes
 
-      # Creates a new instance that wraps +params+ according to +operation+.
-      # References are resolved to API components in +definitions+.
+      # Creates a new instance that wraps +params+ according to +operation+. References are
+      # resolved to API components in +definitions+.
       #
-      # If +strong+ is true+ parameters that can be mapped are accepted only.
-      # That means that the instance created is invalid if +params+ contains
-      # any parameters that cannot be mapped to a parameter or a request body
-      # property of +operation+.
+      # If +strong+ is true+ parameters that can be mapped are accepted only. That means that
+      # the instance created is invalid if +params+ contains any parameters that can't be
+      # mapped to a parameter or a request body property of +operation+.
       def initialize(params, operation, definitions, strong: false)
         @params = params
         @strong = strong == true
@@ -43,8 +42,8 @@ module Jsapi
         "#{attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
       end
 
-      # Validates the request parameters. Returns true if the parameters are
-      # valid, false otherwise. Detected errors are added to +errors+.
+      # Validates the request parameters. Returns true if the parameters are valid, false
+      # otherwise. Detected errors are added to +errors+.
       def validate(errors)
         [
           validate_attributes(errors),

data/lib/jsapi/controller/parameters_invalid.rb

@@ -11,8 +11,7 @@ module Jsapi
         super('')
       end
 
-      # Overrides <code>StandardError#message</code> to lazily generate the
-      # error message.
+      # Overrides <code>StandardError#message</code> to lazily generate the error message.
       def message
         "#{
           @params.errors.full_messages.map do |message|

data/lib/jsapi/controller/response.rb

@@ -5,8 +5,8 @@ module Jsapi
     # Used to serialize a response.
     class Response
 
-      # Creates a new instance to serialize +object+ according to +response+.
-      # References are resolved to API components in +definitions+.
+      # Creates a new instance to serialize +object+ according to +response+. References are
+      # resolved to API components in +definitions+.
       def initialize(object, response, definitions)
         @object = object
         @response = response

data/lib/jsapi/dsl/callbacks.rb

@@ -3,7 +3,7 @@
 module Jsapi
   module DSL
     module Callbacks
-      # Defines an OpenAPI callback or refers a reusable callback.
+      # Defines an \OpenAPI callback or refers a reusable callback.
       #
       #   # define a callback
       #   callback 'foo' do

data/lib/jsapi/dsl/definitions.rb

@@ -12,7 +12,7 @@ module Jsapi
         end
       end
 
-      # Defines the root of an OpenAPI document.
+      # Defines the root of an \OpenAPI document.
       #
       #   openapi do
       #     info title: 'Foo', version: '1'
@@ -63,8 +63,8 @@ module Jsapi
         end
       end
 
-      # Specifies the HTTP status code of an error response rendered when an
-      # exception of any of +klasses+ has been raised.
+      # Specifies the HTTP status code of an error response rendered when an exception of
+      # any of +klasses+ has been raised.
       #
       #   rescue_from Jsapi::Controller::ParametersInvalid, with: 400
       #

data/lib/jsapi/dsl/error.rb

@@ -5,8 +5,7 @@ module Jsapi
     # Raised when an error occurred while defining an API component.
     class Error < StandardError
 
-      # Creates a new error. +origin+ is the innermost position at where
-      # the error occurred.
+      # Creates a new error. +origin+ is the innermost position at where the error occurred.
       def initialize(error_or_message, origin = nil)
         @path = Array(origin)
         super(
@@ -18,9 +17,8 @@ module Jsapi
         )
       end
 
-      # Overrides <code>StandardError#message</code> to append the whole path of
-      # the position at where the error occurred, for example:
-      # <code>{message} (at foo / bar)</code>.
+      # Overrides <code>StandardError#message</code> to append the whole path of the position
+      # at where the error occurred, for example: <code>{message} (at foo / bar)</code>.
       def message
         message = super
         return message if @path.empty?

data/lib/jsapi/dsl/examples.rb

@@ -3,7 +3,7 @@
 module Jsapi
   module DSL
     module Examples
-      # Defines an example.
+      # Adds an example.
       #
       #   example 'foo', value: 'bar'
       #

data/lib/jsapi/dsl/openapi/callback.rb

@@ -6,7 +6,7 @@ module Jsapi
       # Used to specify details of a callback.
       class Callback < Node
 
-        # Defines a callback operation.
+        # Adds a callback operation.
         #
         #   operation '{$request.query.foo}' do
         #     parameter 'bar', type: 'string'

data/lib/jsapi/dsl/openapi/root.rb

@@ -3,9 +3,123 @@
 module Jsapi
   module DSL
     module OpenAPI
-      # Used to specify details of an OpenAPI object.
+      # Used to specify details of an \OpenAPI object.
       class Root < Node
         include Callbacks
+
+        ##
+        # :method: base_path
+        # :args: arg
+        # Specifies the base path of the API.
+        #
+        #   base_path '/foo'
+        #
+        # See Meta::OpenAPI::Root#base_path for further information.
+
+        ##
+        # :method: consumes
+        # :args: mime_types
+        # Specifies one or more MIME types the API can consume.
+        #
+        #   consumes 'application/json'
+        #
+        #   consumes %w[application/json application/pdf]
+        #
+        # See Meta::OpenAPI::Root#consumes for further information.
+
+        ##
+        # :method: external_docs
+        # :args: **keywords, &block
+        # Specifies the external documentation.
+        #
+        #   external_docs url: 'https://foo.bar'
+        #
+        # See Meta::OpenAPI::Root#external_docs for further information.
+
+        ##
+        # :method: host
+        # :args: arg
+        # Specifies the host serving the API.
+        #
+        #   host 'foo.bar'
+        #
+        # See Meta::OpenAPI::Root#host for further information.
+
+        ##
+        # :method: info
+        # :args: **keywords, &block
+        # Specifies general information about the API.
+        #
+        #   info title: 'foo', version: 1
+        #
+        # See Meta::OpenAPI::Root#info for further information.
+
+        ##
+        # :method: link
+        # :args: name, **keywords, &block
+        # Adds a link.
+        #
+        #   link 'foo', operation_id: 'bar'
+        #
+        # See Meta::OpenAPI::Root#links for further information.
+
+        ##
+        # :method: produces
+        # :args: mime_types
+        # Specifies one or more MIME types the API can produce.
+        #
+        #   produces 'application/json'
+        #
+        #   produces %w[application/json application/pdf]'
+        #
+        # See Meta::OpenAPI::Root#produces for further information.
+
+        ##
+        # :method: scheme
+        # :args: arg
+        # Adds a URI scheme supported by the API.
+        #
+        #   scheme 'https'
+        #
+        # See Meta::OpenAPI::Root#scheme for further information.
+
+        ##
+        # :method: security_requirement
+        # :args: **keywords, &block
+        # Adds a security requirement.
+        #
+        #   security_requirement do
+        #     scheme 'basic_auth'
+        #   end
+        #
+        # See Meta::OpenAPI::Root#security_requirements for further information.
+
+        ##
+        # :method: security_scheme
+        # :args: name, **keywords, &block
+        # Adds a security scheme.
+        #
+        #   security_scheme 'basic_auth', type: 'http', scheme: 'basic'
+        #
+        # See Meta::OpenAPI::Root#security_schemes for further information.
+
+        ##
+        # :method: server
+        # :args: arg
+        # Adds a server providing the API.
+        #
+        #   server url: 'https://foo.bar'
+        #
+        # See Meta::OpenAPI::Root#servers for further information.
+
+        ##
+        # :method: tag
+        # :args: **keywords, &block
+        # Adds a tag.
+        #
+        #   tag name: 'foo', description: 'description of foo'
+        #
+        # See Meta::OpenAPI::Root#tags for further information.
       end
     end
   end

data/lib/jsapi/dsl/operation.rb

@@ -6,12 +6,28 @@ module Jsapi
     class Operation < Node
       include Callbacks
 
-      # Overrides Object#method to handle +method+ as a keyword.
-      def method(method) # :nodoc:
-        _keyword(:method, method)
+      ##
+      # :method: deprecated
+      # :args: arg
+      # Specifies whether or not the operation is deprecated.
+      #
+      #   deprecated true
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the description of the operation.
+
+      # Specifies the HTTP verb of the operation.
+      #
+      #   method 'post'
+      #
+      # See Meta::Operation#method for further information.
+      def method(arg)
+        _keyword(:method, arg)
       end
 
-      # Specifies the model class to access top-level parameters by.
+      # Defines the model class to access top-level parameters by.
       #
       #   model Foo do
       #     def bar
@@ -19,9 +35,8 @@ module Jsapi
       #     end
       #   end
       #
-      # +klass+ can be any subclass of Model::Base. If block is given, an
-      # anonymous class is created that inherits either from +klass+ or
-      # Model::Base.
+      # +klass+ can be any subclass of Model::Base. If block is given, an anonymous class
+      # is created that inherits either from +klass+ or Model::Base.
       def model(klass = nil, &block)
         if block
           klass = Class.new(klass || Model::Base)
@@ -30,7 +45,7 @@ module Jsapi
         _meta_model.model = klass
       end
 
-      # Defines a parameter or refers a reusable parameter.
+      # Adds a parameter or a reference to a reusable parameter.
       #
       #   # define a parameter
       #   parameter 'foo', type: 'string'
@@ -43,8 +58,8 @@ module Jsapi
       #   # refer a reusable parameter
       #   parameter ref: 'foo'
       #
-      # Refers the reusable parameter with the same name if neither any
-      # keywords nor a block is specified.
+      # Refers the reusable parameter with the same name if neither any keywords nor a
+      # block is specified.
       #
       #   parameter 'foo'
       #
@@ -58,6 +73,11 @@ module Jsapi
         end
       end
 
+      ##
+      # :method: path
+      # :args: arg
+      # Specifies the relative path of the operation.
+
       # Defines the request body or refers a reusable request body.
       #
       #   # define a request body
@@ -80,7 +100,7 @@ module Jsapi
         end
       end
 
-      # Defines a response or refers a reusable response.
+      # Adds a response or a reference to a reusable response.
       #
       #   # define a response
       #   response 200, type: 'object' do
@@ -113,6 +133,25 @@ module Jsapi
           _eval(response_model, Response, &block)
         end
       end
+
+      ##
+      # :method: summary
+      # :args: arg
+      # Specifies the short summary of the operation.
+
+      ##
+      # :method: tag
+      # :args: name
+      # Adds a tag.
+      #
+      #   tag 'foo'
+
+      ##
+      # :method: tags
+      # :args: names
+      # Specifies all of the tags at once.
+      #
+      #   tags %w[foo bar]
     end
   end
 end

data/lib/jsapi/dsl/parameter.rb

@@ -5,6 +5,35 @@ module Jsapi
     # Used to specify details of a parameter.
     class Parameter < Schema
       include Examples
+
+      ##
+      # :method: deprecated
+      # :args: arg
+      # Specifies whether or not the parameter is deprecated.
+      #
+      #   deprecated true
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the description of the parameter.
+
+      ##
+      # :method: in
+      # :args: location
+      # Specifies the location of the parameter.
+      #
+      # See Meta::Parameter::Model#in for further information.
+
+      ##
+      # :method: ref
+      # :args: name
+      # Specifies the name of the reusable parameter to be referred.
+
+      ##
+      # :method: schema
+      # :args: name
+      # Specifies the name of the reusable schema to be referred.
     end
   end
 end

data/lib/jsapi/dsl/request_body.rb

@@ -5,6 +5,28 @@ module Jsapi
     # Used to specify details of a request body.
     class RequestBody < Schema
       include Examples
+
+      ##
+      # :method: deprecated
+      # :args: arg
+      # Specifies whether or not the request body is deprecated.
+      #
+      #   deprecated true
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the description of the request body.
+
+      ##
+      # :method: ref
+      # :args: name
+      # Specifies the name of the reusable request body to be referred.
+
+      ##
+      # :method: schema
+      # :args: name
+      # Specifies the name of the reusable schema to be referred.
     end
   end
 end

data/lib/jsapi/dsl/response.rb

@@ -6,6 +6,18 @@ module Jsapi
     class Response < Schema
       include Examples
 
+      ##
+      # :method: deprecated
+      # :args: arg
+      # Specifies whether or not the response is deprecated.
+      #
+      #   deprecated true
+
+      ##
+      # :method: description
+      # :args: arg
+      # Specifies the description of the response.
+
       # Defines a link or refers a reusable link object.
       #
       #   # define a link
@@ -28,6 +40,23 @@ module Jsapi
           Node.new(link_model, &block) if block
         end
       end
+
+      ##
+      # :method: locale
+      # :args: arg
+      # Specifies the locale to be used when rendering a response.
+      #
+      #   locale :en
+
+      ##
+      # :method: ref
+      # :args: name
+      # Specifies the name of the reusable response to be referred.
+
+      ##
+      # :method: schema
+      # :args: name
+      # Specifies the name of the reusable schema to be referred.
     end
   end
 end