Module: Serega::SeregaPlugins::OpenAPI

Defined in:
lib/serega/plugins/openapi/openapi.rb,
lib/serega/plugins/openapi/lib/modules/config.rb,
lib/serega/plugins/openapi/lib/openapi_config.rb

Overview

Plugin :openapi

Helps to build OpenAPI schemas

This schemas can be easielty used with “rswag” gem by adding them to “config.swagger_docs”

https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions

This plugin only adds type “object” or “array” for relationships and marks attributes as required if they have no :hide option set.

OpenAPI properties will have no any “type” or other options specified by default, you should provide them in ‘YourSerializer.openapi_properties’ method. ‘openapi_properties` can be specified multiple time, in this case they wil be merged.

After enabling this plugin attributes with :serializer option will have to have :many option set to construct “object” or “array” openapi type for relationships.

OpenAPI ‘$ref` property will be added automatically for all relationships.

Example constructing all serializers schemas:

`Serega::OpenAPI.schemas`

Example constructing specific serializers schemas:

`Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`

Example constructing one serializer schema:

`SomeSerializer.openapi_schema`

Examples:

class BaseSerializer < Serega
  plugin :openapi
end

class UserSerializer < BaseSerializer
  attribute :name

  openapi_properties(
    name: { type: :string }
  )
end

class PostSerializer < BaseSerializer
  attribute :text
  attribute :user, serializer: UserSerializer, many: false
  attribute :comments, serializer: PostSerializer, many: true, hide: true

  openapi_properties(
    text: { type: :string },
    user: { type: 'object' }, # `$ref` option will be added automatically when constructing schema
    comments: { type: 'array' } # `items` option with `$ref` will be added automatically when constructing schema
  )
end

puts Serega::OpenAPI.schemas
=>
{
  "PostSerializer" => {
    type: "object",
    properties: {
      text: {type: "string"},
      user: {:$ref => "#/components/schemas/UserSerializer"},
      comments: {type: "array", items: {:$ref => "#/components/schemas/PostSerializer"}}
    },
    required: [:text, :comments],
    additionalProperties: false
  },
  "UserSerializer" => {
    type: "object",
    properties: {
      name: {type: "string"}
    },
    required: [:name],
    additionalProperties: false
  }
}

Defined Under Namespace

Modules: ClassMethods, ConfigInstanceMethods Classes: OpenAPIConfig

Constant Summary collapse

DEFAULT_SCHEMA_NAME_BUILDER =

Builder for schema name (used is schemas list). Returns serializer class name

->(serializer_class) { serializer_class.name }
DEFAULT_REF_BUILDER =

Builder for $ref openapi property

->(serializer_class) { "#/components/schemas/#{serializer_class.openapi_schema_name}" }

Class Method Summary collapse

Class Method Details

.after_load_plugin(serializer_class, **opts) ⇒ void

This method returns an undefined value.

Adds config options and runs other callbacks after plugin was loaded

Parameters:

  • serializer_class (Class<Serega>) —

    Current serializer class

  • opts (Hash) —

    loaded plugins opts



165
166
167
 
# File 'lib/serega/plugins/openapi/openapi.rb', line 165

def self.after_load_plugin(serializer_class, **opts)
  Serega::OpenAPI.serializers << serializer_class unless serializer_class.equal?(Serega)
end

.before_load_plugin(serializer_class, **opts) ⇒ void

This method returns an undefined value.

Checks requirements and loads additional plugins

Parameters:

  • serializer_class (Class<Serega>) —

    Current serializer class

  • opts (Hash) —

    loaded plugins opts



129
130
131
132
133
 
# File 'lib/serega/plugins/openapi/openapi.rb', line 129

def self.before_load_plugin(serializer_class, **opts)
  unless serializer_class.plugin_used?(:explicit_many_option)
    serializer_class.plugin :explicit_many_option
  end
end

.load_plugin(serializer_class, **opts) ⇒ void

This method returns an undefined value.

Applies plugin code to specific serializer

Parameters:

  • serializer_class (Class<Serega>) —

    Current serializer class

  • _opts (Hash) —

    Loaded plugins options



143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/serega/plugins/openapi/openapi.rb', line 143

def self.load_plugin(serializer_class, **opts)
  require_relative "./lib/modules/config"
  require_relative "./lib/openapi_config"

  serializer_class.extend(ClassMethods)
  serializer_class::SeregaConfig.include(ConfigInstanceMethods)

  config = serializer_class.config
  config.opts[:openapi] = {properties: {}}
  openapi_config = serializer_class.config.openapi
  openapi_config.schema_name_builder = opts[:schema_name_builder] || DEFAULT_SCHEMA_NAME_BUILDER
  openapi_config.ref_builder = opts[:ref_builder] || DEFAULT_REF_BUILDER
end

.plugin_name ⇒ Symbol

Returns Plugin name.

Returns:

  • (Symbol) —

    Plugin name



118
119
120
 
# File 'lib/serega/plugins/openapi/openapi.rb', line 118

def self.plugin_name
  :openapi
end