issue#566: removes markdown (#567)

- updates README
- updates UPGRADING
- adds changelog entry
- cleans up gemfile

Author: peter scholz

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 #### Features
 
+* [#567](https://github.com/ruby-grape/grape-swagger/pull/567): Issue#566: removes markdown - [@LeFnord](https://github.com/LeFnord).
+
 * Your contribution here.
 
 #### Fixes

Gemfile

@@ -15,19 +15,16 @@ gem ENV['MODEL_PARSER'] if ENV.key?('MODEL_PARSER')
 
 group :development, :test do
   gem 'bundler'
-  gem 'kramdown'
   gem 'pry', platforms: [:mri]
   gem 'pry-byebug', platforms: [:mri]
   gem 'rack'
   gem 'rack-cors'
   gem 'rack-test'
   gem 'rake'
   gem 'rdoc'
-  gem 'redcarpet', '< 3.4', platforms: [:mri]
-  gem 'rouge', platforms: [:mri]
   gem 'rspec', '~> 3.0'
   gem 'rubocop', '~> 0.40'
-  gem 'shoulda'
+  # gem 'shoulda'
 end
 group :test do
   gem 'grape-entity'

README.md

@@ -16,7 +16,7 @@
 * [Routes Configuration](#routes)
 * [Using Grape Entities](#grape-entity)
 * [Securing the Swagger UI](#oauth)
-* [Markdown](#md_usage)
+* [Markdown (deprecated)](#md_usage)
 * [Example](#example)
 * [Rake Tasks](#rake)
 
@@ -196,7 +196,6 @@ end
 * [add_base_path](#add_base_path)
 * [add_version](#add_version)
 * [doc_version](#doc_version)
-* [markdown](#markdown)
 * [endpoint_auth_wrapper](#endpoint_auth_wrapper)
 * [swagger_endpoint_guard](#swagger_endpoint_guard)
 * [token_owner](#token_owner)
@@ -268,18 +267,8 @@ add_swagger_documentation \
 ```
 
 <a name="markdown" />
-#### markdown:
-Allow markdown in `detail`, default is `false`. (disabled) See [below](#md_usage) for details.
-
-```ruby
-add_swagger_documentation \
-  markdown: GrapeSwagger::Markdown::KramdownAdapter.new
-```
-or alternative
-```ruby
-add_swagger_documentation \
-  markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
-```
+#### markdown: (deprecated)
+OAPI accepts GFM for descriptions
 
 <a name="endpoint_auth_wrapper" />
 #### endpoint_auth_wrapper:
@@ -1087,77 +1076,11 @@ The lambda is checking whether the user is authenticated (if not, the token_owne
 role - only admins can see this endpoint.
 
 <a name="md_usage" />
-## 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).
-The adapters are packed in the GrapeSwagger::Markdown modules. We do not include the markdown gems in our gemfile, so be sure to include or install the depended gems.
-
-To use it, add a new instance of the adapter to the markdown options of `add_swagger_documentation`, such as:
-```ruby
-add_swagger_documentation \
-  markdown: GrapeSwagger::Markdown::KramdownAdapter.new(options)
-```
-and write your route details in GFM, examples could be find in [details spec](blob/master/spec/swagger_v2/api_swagger_v2_detail_spec.rb)
-
-
-#### Kramdown
-If you want to use kramdown as markdown formatter, you need to add kramdown to your gemfile.
-
-```ruby
-gem 'kramdown'
-```
-
-Configure your api documentation route with:
-```ruby
-add_swagger_documentation \
-  markdown: GrapeSwagger::Markdown::KramdownAdapter.new(options)
-```
-
+## Markdown in Detail (deprecated)
 
-#### Redcarpet
-As alternative you can use [redcarpet](https://github.com/vmg/redcarpet) as formatter, you need to include redcarpet in your gemspec. If you also want to use [rouge](https://github.com/jneen/rouge) as syntax highlighter you also need to include it.
-
-```ruby
-gem 'redcarpet'
-gem 'rouge'
-```
-
-Configure your api documentation route with:
-
-```ruby
-add_swagger_documentation(
-  markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new(render_options: { highlighter: :rouge })
-)
-```
-
-Alternatively you can disable rouge by adding `:none` as highlighter option. You can add redcarpet extensions and render options trough the `extenstions:` and `render_options:` parameters.
-
-
-#### Custom markdown formatter
-
-You can also add your custom adapter for your favourite markdown formatter, as long it responds to the method `markdown(text)` and it formats the given text.
-
-
-```ruby
-module API
-
-  class FancyAdapter
-   attr_reader :adapter
-
-   def initialize(options)
-    require 'superbmarkdownformatter'
-    @adapter = SuperbMarkdownFormatter.new options
-   end
-
-   def markdown(text)
-      @adapter.render_supreme(text)
-   end
-  end
-
-  add_swagger_documentation markdown: FancyAdapter.new(no_links: true)
-end
-```
+Usage of option `markdown` won't no longer be supported,
+cause OAPI accepts [GFM](https://help.github.com/articles/github-flavored-markdown) and plain text.
+(see: [description of `Info`](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object))
 
 
 <a="example" />

UPGRADING.md

@@ -1,5 +1,11 @@
 ## Upgrading Grape-swagger
 
+### Upgrading to >= 0.26.0
+
+Usage of option `markdown` won't no longer be supported,
+cause OAPI accepts [GFM](https://help.github.com/articles/github-flavored-markdown) and plain text.
+(see: [description of `Info`](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object))
+
 ### Upgrading to >= 0.25.2
 
 Avoids ambiguous documentation of array parameters,

lib/grape-swagger.rb

@@ -7,9 +7,6 @@
 require 'grape-swagger/doc_methods'
 require 'grape-swagger/model_parsers'
 
-require 'grape-swagger/markdown/kramdown_adapter'
-require 'grape-swagger/markdown/redcarpet_adapter'
-
 module GrapeSwagger
   class << self
     def model_parsers

lib/grape-swagger/doc_methods.rb

@@ -27,6 +27,9 @@ def mount_path
     end
 
     def setup(options)
+      # FIXME: move out after next minor is released
+      GrapeSwagger::Errors::SwaggerSpecDeprecated.tell!(options[:markdown]) if options.key?(:markdown)
+
       options = defaults.merge(options)
 
       # options could be set on #add_swagger_documentation call,
@@ -93,7 +96,6 @@ def defaults
         base_path: nil,
         add_base_path: false,
         add_version: true,
-        markdown: false,
         hide_documentation_path: true,
         format: :json,
         authorizations: nil,

lib/grape-swagger/endpoint.rb

@@ -105,12 +105,12 @@ def path_item(routes, options)
     def method_object(route, options, path)
       method = {}
       method[:summary]     = summary_object(route)
-      method[:description] = description_object(route, options[:markdown])
+      method[:description] = description_object(route)
       method[:produces]    = produces_object(route, options[:produces] || options[:format])
       method[:consumes]    = consumes_object(route, options[:format])
       method[:parameters]  = params_object(route)
       method[:security]    = security_object(route)
-      method[:responses]   = response_object(route, options[:markdown])
+      method[:responses]   = response_object(route)
       method[:tags]        = route.options.fetch(:tags, tag_object(route))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method.delete_if { |_, value| value.blank? }
@@ -130,10 +130,9 @@ def summary_object(route)
       summary
     end
 
-    def description_object(route, markdown)
+    def description_object(route)
       description = route.description if route.description.present?
       description = route.options[:detail] if route.options.key?(:detail)
-      description = markdown.markdown(description.to_s).chomp if markdown
 
       description
     end
@@ -178,7 +177,7 @@ def params_object(route)
       parameters
     end
 
-    def response_object(route, markdown)
+    def response_object(route)
       codes = (route.http_codes || route.options[:failure] || [])
 
       codes = apply_success_codes(route) + codes
@@ -199,7 +198,7 @@ def response_object(route, markdown)
         next unless !response_model.start_with?('Swagger_doc') &&
                     ((@definitions[response_model] && value[:code].to_s.start_with?('2')) || value[:model])
 
-        @definitions[response_model][:description] = description_object(route, markdown)
+        @definitions[response_model][:description] = description_object(route)
         # TODO: proof that the definition exist, if model isn't specified
         reference = { '$ref' => "#/definitions/#{response_model}" }
         memo[value[:code]][:schema] = if route.options[:is_array]

lib/grape-swagger/errors.rb

@@ -1,12 +1,13 @@
 module GrapeSwagger
   module Errors
-    class MarkdownDependencyMissingError < StandardError
-      def initialize(missing_gem)
-        super("Missing required dependency: #{missing_gem}")
-      end
-    end
-
     class UnregisteredParser < StandardError; end
     class SwaggerSpec < StandardError; end
+    class SwaggerSpecDeprecated < SwaggerSpec
+      class << self
+        def tell!(what)
+          warn "[GrapeSwagger] usage of #{what} is deprecated"
+        end
+      end
+    end
   end
 end