swaggard 2.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21148d73c5de69058c02b8ea95a396ed2efee41b23ba4db664235a3cf7486cfa
-  data.tar.gz: b40da15f195ec2c8be0b27cf0bce4aced8852c337bd31ab87ad654b5127c12b0
+  metadata.gz: c18dab011ccdb176dd6324a815a0138f051d85cb9383a60681a857c886d516a5
+  data.tar.gz: b8bd9f253e75c56c5308bae421f92cd12b54457edc40aa3d2857b1ac15d1764a
 SHA512:
-  metadata.gz: 4f955faa13d67310fa58904511eabd01677d8927f911b993fc5c4b8674cbdc546d89a87c6f69040a988c772d896be54c20c779c61d7fb86d6eacb61dc286bea4
-  data.tar.gz: be76ce911cf5c32c86ae7c44b3c57cee2aae4fed10d0de24d8ed9b5213cf42a3498e7f503dea5b898b7b80bccfd4b62ff6f8033cbfbd3a5dcd8a8593d260720d
+  metadata.gz: a8406ac609bb110a3cb6d67647e5d775db2d293f0ab754020920442a86f202b80064da43843e616144f084ec9d93694b4bd086119f92413c055bd68d80266bb0
+  data.tar.gz: 5caa69ecc7b014dccca548a27cdad88428c30f423ff2d922104fef04d0861b7f083af89cd7c0aec21d5f9a52e4173bd822cfb5757cb7bfe245100e3f84481d27

data/README.md

@@ -1,25 +1,23 @@
 # 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).
+Swaggard is a Rails Engine that documents a REST API by generating a JSON file compliant with [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) and displaying it using [Swagger UI 5](https://github.com/swagger-api/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
----------------- | ------------------- | ------------------------
-2.0.x            | 2.2.8               | 7 - 8
-1.1.x            | 2.2.8               | 4 - 6
-1.0.x            | 2.2.8               | 4 - 5
-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
+Swaggard Version | OpenAPI Version | Swagger UI Version  | Supported Rails Versions
+---------------- | --------------- | ------------------- | ------------------------
+4.0.x            | 3.1             | 5.32.0              | 7 - 8
+2.0.x            | 2.0             | 2.2.8               | 7 - 8
+1.1.x            | 2.0             | 2.2.8               | 4 - 6
+1.0.x            | 2.0             | 2.2.8               | 4 - 5
+0.5.x            | 2.0             | 2.2.8               | 4 - 5
+0.4.x            | 2.0             | 2.2.8               | 4
+0.3.x            | 2.0             | 2.1.3               | 4
+0.2.x            | 2.0             | 2.1.3               | 4
+0.1.x            | 2.0             | 2.1.3               | 4
+0.0.x            | 2.0             | 2.1.8-M1            | 4
 
 
 ## Installation
@@ -32,47 +30,35 @@ Install the gem with Bundler:
 
     bundle install
 
+
 ## Getting Started
 
-First generate a Swaggard configuration initializer file.
+Generate a Swaggard configuration initializer:
 
     rails g swaggard:install
 
-This will install the file `swaggard.rb` to your Rails `config/initializers` directory which you can then alter the config.
-
-Mount your engine
-
-	# config/routes.rb
-
-	mount Swaggard::Engine, at: '/api_docs/swagger/'
-
-Make sure the asset pipeline is enabled by either requiring all railties
-or just the sprockets one:
-
-    # config/application.rb
+This installs `config/initializers/swaggard.rb` which you can edit to configure the gem.
 
-    require 'sprockets/railtie'
+Mount the engine:
 
-Access your service documentation
+    # config/routes.rb
+    mount Swaggard::Engine, at: '/api_docs/swagger/'
 
-	open http://localhost:3000/api_docs/swagger/
+Access the documentation UI:
 
+    open http://localhost:3000/api_docs/swagger/
 
-Access the raw swagger json
+Access the raw OpenAPI JSON:
 
-	open http://localhost:3000/api_docs/swagger.json
+    open http://localhost:3000/api_docs/swagger.json
 
 
 ## 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
-each path.
-
-This is fine base but you should add more documentation in order to provide more information
-of the expected inputs and outputs or even change the grouping of the endpoints.
+HTTP method, path, and path parameters. Grouping is done based on the controller that holds each path.
 
-Here is a example of how to use Swaggard
+Add YARD comments to provide richer documentation:
 
     # config/routes.rb
 
@@ -146,40 +132,43 @@ Here is a example of how to use Swaggard
 
     end
 
-Will generate
-
-![Web UI](https://raw.githubusercontent.com/Moove-it/swaggard/master/example/web-ui.png)
 
-
-## Available tags
+## Available Tags
 
 ### Controllers
 
-- `@tag name` This is used to indicate under what `name` tag this controller needs to be grouped. If not provided and `!ignore_untagged_controllers` 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`
-
-If you want to generate documentation for all controllers even for those that don't have a tag do:
-    # config/initializers/swaggard.rb
+- `@tag name` — Group this controller under `name`. Defaults to the controller path if `ignore_untagged_controllers` is false.
+- `@query_parameter [type] name` — Query string parameter.
+- `@body_parameter [type] name` — Request body property. Generates a `requestBody` in the OpenAPI output.
+- `@form_parameter [type] name` — Form data parameter (`application/x-www-form-urlencoded`).
+- `@parameter_list` — Enum-style query parameter list.
+- `@response_class type` — Response schema type. Supports `Array<Type>` for array responses.
+- `@response_status 200` — HTTP response status code.
+- `@response_root name` — Wrap the response in a root key.
+- `@response_description text` — Description for the response.
+- `@response_example path/to/example.json` — Example response. Inlined if the file exists on disk, otherwise used as an `externalValue` URI.
+- `@response_header [type] name description` — Response header.
+- `@operation_id id` — Override the `operationId`.
+- `@body_required` — Mark the request body as required.
+- `@body_title title` — Title for the generated request body schema.
+- `@body_definition SchemaName` — Reference an existing schema by name as the request body.
+
+To document all controllers including those without a `@tag`:
+
     Swaggard.configure do |config|
-      ...
       config.ignore_untagged_controllers = false
-      ...
     end
 
 
 ### Models
 
-- `@attr [type] name` This is used to indicate that your models has an attribute `name` of `type`.
+- `@attr [type] name` — Model attribute.
+- `@ignore_inherited` — Do not inherit properties from parent class.
+
 
 ## Primitives
 
-When one of these types is given Swaggard will handle them directly instead of searching for a definition:
+When one of these types is used Swaggard maps it to an inline schema instead of a `$ref`:
 
 - integer
 - long
@@ -195,128 +184,92 @@ When one of these types is given Swaggard will handle them directly instead of s
 - hash
 
 
-## Authentication
-
-Swaggard supports two types of authentication: header and query.
+## Custom Types
 
-You can configure it as follows:
+Define reusable object schemas that are placed in `components/schemas` and referenced via `$ref`:
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      config.authentication_type  = 'header' # Defaults to 'query'
-      config.authentication_key   = 'X-AUTH-TOKEN' # Defaults to 'api_key'
-      config.authentication_value = 'your-secret-key' # Initial value for authentication. Defaults to ''
+      config.add_custom_type('Address', type: :object,
+        properties: {
+          line1: { type: :string },
+          city:  { type: :string },
+          state: { type: :string },
+          zip:   { type: :string },
+        },
+        required: %i[line1 city state zip])
     end
 
-Even if you provide a authentication_value you can later change it from the ui.
 
+## Authentication
 
-## Access authorization
-
-Swaggard supports access authorization.
-
-You can configure it as follows:
+Swaggard supports injecting auth credentials into every request via `requestInterceptor`.
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      config.access_username  = 'admin'
-      config.access_password   = 'password'
+      config.authentication_type  = 'header' # or 'query'. Defaults to 'query'
+      config.authentication_key   = 'X-AUTH-TOKEN' # Defaults to 'api_key'
+      config.authentication_value = 'your-secret-key' # Defaults to ''
     end
 
-If you not set `access_username`, everyone will have access to Swagger documentation.
-
-
-## Additional parameters
+For OAuth2 / API key schemes visible in the Swagger UI Authorize dialog, use `add_security_definition` and `add_security`:
 
-Swaggard supports additional parameters to be sent on every request, either as a header or as part of the query.
-
-You can configure it as follows:
-
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      config.additional_parameters = [{ key: 'TOKEN', type: 'header', value: '234' }]
+      config.add_security_definition('api_key', type: 'apiKey', name: 'Authorization', in: 'header')
+      config.add_security('api_key')
     end
 
-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
+## Access Authorization
 
-You can set default content type in Swaggard configuration as follows:
+Protect the documentation UI with HTTP Basic auth:
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      config.default_content_type = 'application/json'
+      config.access_username = 'admin'
+      config.access_password = 'password'
     end
 
-If you set `default_content_type`, Swagger will use it in example request.
+If `access_username` is not set, the UI is publicly accessible.
 
 
-## Language
+## Additional Parameters
 
-You can set the language for SwaggerUI as follows:
+Inject extra headers or query parameters into every request:
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      config.language = 'es'
+      config.additional_parameters = [{ key: 'STORE-CODE', type: 'header', value: '1' }]
     end
 
-The default value is: 'en'.
-Supported values are:
-- ca
-- el
-- en
-- es
-- fr
-- geo
-- it
-- ja
-- ko-kr
-- pl
-- pt
-- ru
-- tr
-- zh-cn
+`type` can be `'header'` or `'query'`.
 
 
 ## Caching
 
-You can improve Swagger performance by using caching. You can enable `use_cache` in Swaggard configuration as follows:
+Cache the generated OpenAPI JSON for better performance:
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
       config.use_cache = Rails.env.production?
     end
 
-If you set `use_cache` as `Rails.env.production?`, Swagger will use cache only in production mode.
+Clear the cache with:
 
-Note. For cache clearing you can execute `rake swaggard:clear_cache`.
+    rake swaggard:clear_cache
 
 
 ## 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
-need do this:
+Limit documentation to a subset of controllers:
 
-    # config/initializers/swaggard.rb
     Swaggard.configure do |config|
-      ...
       config.controllers_path = "#{Rails.root}/app/controllers/api/**/*.rb"
-      ...
     end
 
-The default value for `controllers_path` is `"#{Rails.root}/app/controllers/**/*.rb"`.
+Default: `"#{Rails.root}/app/controllers/**/*.rb"`.
 
 
 ## More Information
 
-- [Swagger](http://swagger.io)
-- [Swagger-ui](https://github.com/wordnik/swagger-ui)
-- [Yard](https://github.com/lsegal/yard)
+- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)
+- [Swagger UI](https://github.com/swagger-api/swagger-ui)
+- [YARD](https://github.com/lsegal/yard)
 
 
 ## Author
@@ -326,5 +279,4 @@ The default value for `controllers_path` is `"#{Rails.root}/app/controllers/**/*
 
 ## 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.
+[Chris Trinh](https://github.com/chtrinh) — author of [SwaggerYard](https://github.com/synctv/swagger_yard), which this gem is inspired by and based on.

data/app/views/swaggard/swagger/index.html.erb

@@ -2,61 +2,59 @@
 <html>
   <head>
     <title>Swagger UI</title>
-
     <%= favicon_link_tag 'swaggard/favicon-32x32.png', sizes: '32x32' %>
     <%= favicon_link_tag 'swaggard/favicon-16x16.png', sizes: '16x16' %>
-
-    <%= stylesheet_link_tag 'swaggard/application', media: :screen %>
-    <%= stylesheet_link_tag 'swaggard/application_print', media: :print %>
-
-    <%= javascript_include_tag 'swaggard/application' %>
-    <%= javascript_include_tag "swaggard/lang/#{Swaggard.configuration.language}" %>
-
-    <%= javascript_tag do %>
-        window.default_content_type = '<%= Swaggard.configuration.default_content_type %>';
-    <% end %>
-
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.32.0/swagger-ui.css">
   </head>
-
-  <body class='swagger-section' data-doc-path='<%= doc_path(format: :json)%>'>
-    <div id='header'>
-      <div class='swagger-ui-wrap'>
-        <a id='logo' href='http://swagger.io'>
-          <%= image_tag 'swaggard/logo_small.png', class: 'logo__img', alt: 'swagger', height: 30, width: 30 %>
-          <span class='logo__title'>swagger</span>
-        </a>
-        <%= form_tag '', id: :api_selector do %>
-
-          <div>
-            <div class='input'><input placeholder='http://example.com/api_docs/swagger.json' id='input_baseUrl' name='baseUrl' type='text'/></div>
-
-            <div class='input'>
-              <input class='additional_parameter' data-parameter-key='<%= @authentication_key %>'
-                                                  data-parameter-type='<%= @authentication_type %>'
-                                                  placeholder='<%= @authentication_key %>'
-                                                  type='text'
-                                                  value='<%= @authentication_value %>'/>
-              </div>
-
-            <div class='input'><a id='explore' class='header__btn' href='#' data-sw-translate>Explore</a></div>
-          </div>
-          <% Swaggard.configuration.additional_parameters.each do |additional_parameter|%>
-            <div class='input'>
-              <input class='additional_parameter' data-parameter-key='<%= additional_parameter[:key] %>'
-                                                  data-parameter-type='<%= additional_parameter[:type] %>'
-                                                  placeholder='<%= additional_parameter[:key] %>'
-                                                  type='text'
-                                                  value='<%= additional_parameter[:value] %>'/>
-              </div>
-          <% end %>
-          <div id='auth_container'></div>
-        <% end %>
-        <br>
-        <br>
-      </div>
-    </div>
-
-    <div id='message-bar' class='swagger-ui-wrap' data-sw-translate>&nbsp;</div>
-    <div id='swagger-ui-container' class='swagger-ui-wrap'></div>
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script id="swagger-config" type="application/json">
+      <%= {
+        url:                  doc_path(format: :json),
+        authType:             @authentication_type,
+        authKey:              @authentication_key,
+        authValue:            @authentication_value,
+        additionalParameters: Swaggard.configuration.additional_parameters
+      }.to_json.html_safe %>
+    </script>
+
+    <script src="https://unpkg.com/swagger-ui-dist@5.32.0/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = function() {
+        var config = JSON.parse(document.getElementById('swagger-config').textContent);
+
+        SwaggerUIBundle({
+          url:         config.url,
+          dom_id:      '#swagger-ui',
+          deepLinking: true,
+          presets:     [SwaggerUIBundle.presets.apis],
+          plugins:     [SwaggerUIBundle.plugins.DownloadUrl],
+          requestInterceptor: function(request) {
+            if (config.authValue) {
+              if (config.authType === 'header') {
+                request.headers[config.authKey] = config.authValue;
+              } else {
+                var url = new URL(request.url);
+                url.searchParams.set(config.authKey, config.authValue);
+                request.url = url.toString();
+              }
+            }
+
+            (config.additionalParameters || []).forEach(function(param) {
+              if (param.type === 'header') {
+                request.headers[param.key] = param.value;
+              } else if (param.type === 'query') {
+                var url = new URL(request.url);
+                url.searchParams.set(param.key, param.value);
+                request.url = url.toString();
+              }
+            });
+
+            return request;
+          }
+        });
+      }
+    </script>
   </body>
 </html>

data/lib/swaggard/api_definition.rb

@@ -34,25 +34,31 @@ module Swaggard
       license = { 'name'  => Swaggard.configuration.license_name }
       license['url'] = Swaggard.configuration.license_url if Swaggard.configuration.license_url.present?
 
-      {
-        'swagger' => Swaggard.configuration.swagger_version,
-        'info' => {
-          'version'         => Swaggard.configuration.api_version,
-          'title'           => Swaggard.configuration.title,
-          'description'     => Swaggard.configuration.description,
-          'termsOfService'  => Swaggard.configuration.tos,
-          'contact'         => contact,
-          'license'         => license,
-        },
-        'host'        => Swaggard.configuration.host,
-        'basePath'    => Swaggard.configuration.api_base_path,
-        'schemes'     => Swaggard.configuration.schemes,
-        'consumes'    => Swaggard.configuration.api_formats.map { |format| "application/#{format}" },
-        'produces'    => Swaggard.configuration.api_formats.map { |format| "application/#{format}" },
-        'tags'        => @tags.map { |_, tag| tag.to_doc },
-        'paths'       => Hash[@paths.values.map { |path| [format_path(path.path), path.to_doc] }],
-        'definitions' => Hash[@definitions.merge(Swaggard.configuration.definitions).map { |id, definition| [id, definition.to_doc(@definitions)] }]
-      }.merge(security_definitions)
+      config = Swaggard.configuration
+      server_url = "#{config.schemes.first}://#{config.host}#{config.api_base_path}"
+
+      info = {
+        'version'         => config.api_version,
+        'title'           => config.title,
+        'description'     => config.description,
+        'contact'         => contact,
+        'license'         => license,
+      }
+      info['termsOfService'] = config.tos if config.tos.present?
+
+      doc = {
+        'openapi' => '3.1.0',
+        'info'    => info,
+        'servers' => [{ 'url' => server_url }],
+        'tags'    => @tags.map { |_, tag| tag.to_doc },
+        'paths'   => Hash[@paths.values.map { |path| [format_path(path.path), path.to_doc] }],
+      }
+
+      components = build_components
+      doc['components'] = components unless components.empty?
+      doc['security'] = config.security unless config.security.empty?
+
+      doc
     end
 
     private
@@ -63,21 +69,29 @@ module Swaggard
       path.gsub(Swaggard.configuration.api_base_path, '')
     end
 
-    def security_definitions
-      security_definitions = Swaggard.configuration.security_definitions
+    def build_components
+      custom_type_schemas = Swaggard.configuration.custom_types
+        .transform_keys { |k| Swaggard.ref_name(k) }
 
-      return {} if security_definitions.empty? && Swaggard.configuration.security.empty?
+      definition_schemas = Hash[
+        @definitions.merge(Swaggard.configuration.definitions)
+          .map { |id, definition| [Swaggard.ref_name(id), definition.to_doc(@definitions)] }
+      ]
+
+      schemas = custom_type_schemas.merge(definition_schemas)
+
+      security_schemes = Swaggard.configuration.security_definitions
 
       Swaggard.configuration.security.flat_map(&:keys).each do |authentication_type|
-        next if security_definitions.key?(authentication_type)
+        next if security_schemes.key?(authentication_type)
 
-        warn "#{authentication_type} not supported by securityDefinitions"
+        warn "#{authentication_type} not supported by components/securitySchemes"
       end
 
-      {
-        'securityDefinitions' => security_definitions,
-        'security' => Swaggard.configuration.security,
-      }
+      result = {}
+      result['schemas'] = schemas unless schemas.empty?
+      result['securitySchemes'] = security_schemes unless security_schemes.empty?
+      result
     end
   end
 end

data/lib/swaggard/configuration.rb

@@ -14,7 +14,7 @@ module Swaggard
 
     attr_accessor :controllers_path, :models_paths, :routes
 
-    attr_writer :swagger_version, :api_base_path, :api_version, :api_formats, :title,
+    attr_writer :api_base_path, :api_version, :api_formats, :title,
                 :description, :tos, :contact_email, :contact_name, :contact_url, :host,
                 :authentication_type, :authentication_key, :authentication_value,
                 :access_username, :access_password, :default_content_type, :use_cache,
@@ -23,10 +23,6 @@ module Swaggard
                 :default_response_status_code, :excluded_paths, :path_parameter_description,
                 :ignore_put_if_patch_exists, :ignore_untagged_controllers
 
-    def swagger_version
-      @swagger_version ||= '2.0'
-    end
-
     def api_version
       @api_version ||= '0.1'
     end

data/lib/swaggard/engine.rb

@@ -9,15 +9,6 @@ module Swaggard
     initializer 'swaggard.finisher_hook', after: :finisher_hook do |app|
       app.reload_routes!
 
-      if Rails.env.development? && !rake? && !app.methods.include?(:assets_manifest)
-        warn <<~END
-        [Swaggard] It seems you are using an api only rails setup, but swaggard
-        [Swaggard] web app needs sprockets in order to work. Make sure to add
-        [Swaggard] require 'sprockets/railtie'.
-        [Swaggard] If you plan to use it
-        END
-      end
-
       Swaggard.configure do |config|
         unless config.controllers_path
           config.controllers_path = "#{app.root}/app/controllers/**/*.rb"
@@ -32,28 +23,5 @@ module Swaggard
 
       Swaggard.register_custom_yard_tags!
     end
-
-    initializer "swaggard.assets.precompile", after: 'assets.precompile' do |app|
-      next unless app.config.respond_to?(:assets)
-
-      app.config.assets.precompile += %w(
-        swaggard/application.css
-        swaggard/application.js
-        swaggard/lang/ca.js
-        swaggard/lang/el.js
-        swaggard/lang/en.js
-        swaggard/lang/es.js
-        swaggard/lang/fr.js
-        swaggard/lang/geo.js
-        swaggard/lang/it.js
-        swaggard/lang/ja.js
-        swaggard/lang/ko-kr.js
-        swaggard/lang/pl.js
-        swaggard/lang/pt.js
-        swaggard/lang/ru.js
-        swaggard/lang/tr.js
-        swaggard/lang/zh-cn.js
-      )
-    end
   end
 end