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 169 def body_params request.request_parameters 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 177 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 r.request_body_class.call(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 r.path_params_class.call(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 r.query_params_class.call(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)] serializer ||= serializer.new if serializer.respond_to?(:new) render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts 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