adds Rake task to get and validate OAPI documentation (#500)

- updates compatibility matrix
- adds changelog entry

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 #### Features
 
+* [#500](https://github.com/ruby-grape/grape-swagger/pull/500): Adds Rake tasks to get and validate OAPI/Swagger documentation - [@LeFnord](https://github.com/LeFnord).
 * [#493](https://github.com/ruby-grape/grape-swagger/pull/493): Swagger UI endpoint authorization. - [@texpert](https://github.com/texpert).
 * [#492](https://github.com/ruby-grape/grape/pull/492): Define security requirements on endpoint methods - [@tomregelink](https://github.com/tomregelink).
 * [#497](https://github.com/ruby-grape/grape-swagger/pull/497): Use ruby-grape-danger in Dangerfile - [@dblock](https://github.com/dblock).

README.md

@@ -19,6 +19,7 @@
 * [Response documentation](#response)
 * [Extensions](#extensions)
 * [Example](#example)
+* [Rake Tasks](#rake)
 
 <a name="what" />
 ## What is grape-swagger?
@@ -51,7 +52,7 @@ grape-swagger | swagger spec | grape                   | grape-entity | represen
 0.20.1        |     2.0      | >= 0.12.0 ... <= 0.14.0 | <= 0.5.1     | n/a           |
 0.20.3        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1     | n/a           |
 0.21.0        |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
-0.21.1 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
+0.23.0        |     2.0      | >= 0.12.0 ... <= 0.17.0 | <= 0.5.1     | >= 2.4.1      |
 
 <a name="swagger-spec" />
 ## Swagger-Spec
@@ -867,7 +868,7 @@ The lambda is checking whether the user is authenticated (if not, the token is n
 role - only admins can see this endpoint. 
 
 <a name="md_usage" />
-### Markdown in Detail
+## Markdown in Detail
 
 The grape-swagger gem allows you to add an explanation in markdown in the detail field. Which would result in proper formatted markdown in Swagger UI.
 Grape-swagger uses adapters for several markdown formatters. It includes adapters for [kramdown](http://kramdown.rubyforge.org) (kramdown [syntax](http://kramdown.rubyforge.org/syntax.html)) and [redcarpet](https://github.com/vmg/redcarpet).
@@ -1061,19 +1062,20 @@ route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }
 ```
 
 <a="example" />
-# Example
+## Example
 
 Go into example directory and run it: `$ bundle exec rackup`
 go to: `http://localhost:9292/swagger_doc` to get it
 
 For request examples load the [postman file]()
-## Grouping the API list using Namespace
+
+#### Grouping the API list using Namespace
 
 Use namespace for grouping APIs
 
 ![grape-swagger-v2-new-corrected](https://cloud.githubusercontent.com/assets/1027590/13516020/979cfefa-e1f9-11e5-9624-f4a6b17a3c8a.png)
 
-# Example
+#### Example Code
 
 ```ruby
 class NamespaceApi < Grape::API
@@ -1105,6 +1107,33 @@ end
 
 ```
 
+
+<a name="rake" />
+## Rake Tasks
+
+Add these lines to your Rakefile, and initialize the Task class with your Api class – be sure your Api class is available.
+
+```ruby
+require 'grape-swagger/rake/oapi_tasks'
+GrapeSwagger::Rake::OapiTasks.new(::Api::Base)
+```
+
+#### OpenApi/Swagger Documentation
+
+```
+rake oapi:fetch
+rake oapi:fetch store=true # writes to swagger_doc.json
+```
+
+#### OpenApi/Swagger Validation
+
+**requires**: `npm` and `swagger-cli` to be installed
+
+```
+rake oapi:validate
+```
+
+
 ## Contributing to grape-swagger
 
 See [CONTRIBUTING](CONTRIBUTING.md).

lib/grape-swagger.rb

@@ -18,6 +18,7 @@ def model_parsers
       @model_parsers ||= GrapeSwagger::ModelParsers.new
     end
   end
+  autoload :Rake, 'grape-swagger/rake/oapi_tasks'
 end
 
 module Grape

lib/grape-swagger/rake/oapi_tasks.rb

@@ -0,0 +1,82 @@
+require 'rake'
+require 'rake/tasklib'
+require 'rack/test'
+
+module GrapeSwagger
+  module Rake
+    class OapiTasks < ::Rake::TaskLib
+      include Rack::Test::Methods
+
+      attr_reader :oapi
+      attr_reader :api_class
+
+      def initialize(api_class)
+        super()
+        @api_class = api_class
+        define_tasks
+      end
+
+      private
+
+      def define_tasks
+        namespace :oapi do
+          fetch
+          validate
+        end
+      end
+
+      # tasks
+      #
+      # get swagger/OpenAPI documentation
+      def fetch
+        desc 'generates OpenApi documentation (`store=true`, stores to FS)'
+        task fetch: :environment do
+          make_request
+          ENV['store'] ? File.write(file, @oapi) : print(@oapi)
+        end
+      end
+
+      # validates swagger/OpenAPI documentation
+      def validate
+        desc 'validates the generated OpenApi file'
+        task validate: :environment do
+          ENV['store'] = 'true'
+          ::Rake::Task['oapi:fetch'].invoke
+
+          output = system "swagger validate #{file}"
+
+          $stdout.puts 'install swagger-cli with `npm install swagger-cli -g`' if output.nil?
+          FileUtils.rm(file)
+        end
+      end
+
+      # helper methods
+      #
+      def make_request
+        get url_for
+        last_response
+        @oapi = JSON.pretty_generate(
+          JSON.parse(
+            last_response.body, symolize_names: true
+          )
+        )
+      end
+
+      def url_for
+        oapi_route = api_class.routes[-2]
+        url = '/swagger_doc'
+        url = "/#{oapi_route.version}#{url}" if oapi_route.version
+        url = "/#{oapi_route.prefix}#{url}" if oapi_route.prefix
+        url
+      end
+
+      def file
+        File.join(Dir.getwd, 'swagger_doc.json')
+      end
+
+      def app
+        api_class.new
+      end
+    end
+  end
+end