module SoberSwag::Controller
This module can be included in any subclass of `ActionController` or `ActionController::API` to make it `SoberSwag`-able. This means that you can use the mechanics of SoberSwag
to define a type-safe API, with generated Swagger documentation!
Public Instance Methods
Obtain a parameters hash of only those parameters which come in the hash. These will be unsafe in the sense that they will all be allowed. This kinda violates the “be liberal in what you accept” principle, but it keeps the docs honest: parameters sent in the body must be in the body.
@return [Hash]
# File lib/sober_swag/controller.rb, line 174 def body_params request.request_parameters end
# File lib/sober_swag/controller.rb, line 186 def build_parsed_sober_swag(parser, params) if parser.respond_to?(:call!) parser.call!(params) else parser.call(params) end end
Get the action-definition for the current action. Under the hood, delegates to the `:action` key of rails params. @return [SoberSwag::Controller::Route]
# File lib/sober_swag/controller.rb, line 182 def current_action_def self.class.find_route(params[:action]) end
Get the request body, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define}. @raise [UndefinedBodyError] if there's no request body defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
# File lib/sober_swag/controller.rb, line 125 def parsed_body @parsed_body ||= begin r = current_action_def raise UndefinedBodyError unless r&.request_body_class build_parsed_sober_swag(r.request_body_class, body_params) end end
Get the path parameters, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define} @raise [UndefinedPathError] if there's no path params defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
# File lib/sober_swag/controller.rb, line 111 def parsed_path @parsed_path ||= begin r = current_action_def raise UndefinedPathError unless r&.path_params_class build_parsed_sober_swag(r.path_params_class, request.path_parameters) end end
Get the query params, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define} @raise [UndefinedQueryError] if there's no query params defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
# File lib/sober_swag/controller.rb, line 139 def parsed_query @parsed_query ||= begin r = current_action_def raise UndefinedQueryError unless r&.query_params_class build_parsed_sober_swag(r.query_params_class, request.query_parameters) end end
Respond with the serialized type that you defined for this route. @todo figure out how to specify views and other options for the serializer here @param status [Symbol] the HTTP status symbol to use for the status code @param entity the thing to serialize
# File lib/sober_swag/controller.rb, line 154 def respond!(status, entity, serializer_opts: {}, rails_opts: {}) r = current_action_def serializer = r.response_serializers[Rack::Utils.status_code(status)] if serializer.respond_to?(:reporting?) && serializer.reporting? serializer = serializer.view(serializer_opts[:view].to_sym) if serializer_opts.key?(:view) render json: serializer.call(entity), status: status, **rails_opts else serializer ||= serializer.new if serializer.respond_to?(:new) render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts end end
ActiveController action to get the swagger definition for this API. It renders a JSON of the OpenAPI v3 schema for this API.
# File lib/sober_swag/controller.rb, line 103 def swagger render json: self.class.swagger_info end