Added UPGRADING instructions.
Support instantiating the markdown adapeter without creating an instance.
This commit is contained in:
Antek Drzewiecki
dblock
parent
1485a60067
commit
4a79e05af0
27
CHANGELOG.md
27
CHANGELOG.md
|
|
@ -1,24 +1,31 @@
|
|||
### Next Release
|
||||
### 0.8.0 (August 27, 2014)
|
||||
|
||||
#### Features
|
||||
|
||||
* [#139](https://github.com/tim-vandecasteele/grape-swagger/pull/139): Added support for `Rack::Multipart::UploadedFile` parameters - [@timgluz](https://github.com/timgluz).
|
||||
* [#136](https://github.com/tim-vandecasteele/grape-swagger/pull/136), [#94](https://github.com/tim-vandecasteele/grape-swagger/pull/94): Recurse combination of namespaces when using mounted apps - [@renier](https://github.com/renier).
|
||||
* [#100](https://github.com/tim-vandecasteele/grape-swagger/pull/100): Added ability to specify a nickname for an endpoint - [@lhorne](https://github.com/lhorne).
|
||||
* [#94](https://github.com/tim-vandecasteele/grape-swagger/pull/94): Added support for namespace descriptions - [@renier](https://github.com/renier).
|
||||
* [#110](https://github.com/tim-vandecasteele/grape-swagger/pull/110), [#111](https://github.com/tim-vandecasteele/grape-swagger/pull/111) - Added `responseModel` support - [@bagilevi](https://github.com/bagilevi).
|
||||
* [#105](https://github.com/tim-vandecasteele/grape-swagger/pull/105): Fixed compatibility with Swagger-UI - [@CraigCottingham](https://github.com/CraigCottingham).
|
||||
* [#87](https://github.com/tim-vandecasteele/grape-swagger/pull/87): Fixed mapping of `default` to `defaultValue` - [@m-o-e](https://github.com/m-o-e).
|
||||
* [#114](https://github.com/tim-vandecasteele/grape-swagger/pull/114): Added support for generating nested models from composed Grape Entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
|
||||
* [#124](https://github.com/tim-vandecasteele/grape-swagger/pull/124): Added ability to change the description and parameters of the API endpoints generated by grape-swagger - [@dblock](https://github.com/dblock).
|
||||
* Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
|
||||
* Added `GrapeEntity::VERSION` - [@dblock](https://github.com/dblock).
|
||||
* Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
|
||||
* [#126](https://github.com/tim-vandecasteele/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
|
||||
* [#127](https://github.com/tim-vandecasteele/grape-swagger/pull/127): Fixed `undefined method 'reject' for nil:NilClass` error for an invalid route, now returning 404 Not Found - [@dblock](https://github.com/dblock).
|
||||
* [#128](https://github.com/tim-vandecasteele/grape-swagger/pull/128): Combine global models and endpoint entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
|
||||
* [#132](https://github.com/tim-vandecasteele/grape-swagger/pull/132): Addes support for enum values in entity documentation and form parameters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
|
||||
* [#135](https://github.com/tim-vandecasteele/grape-swagger/pull/135): Fixed model inclusion in models with aliased references - [@cdarne](https://github.com/cdarne).
|
||||
* [#142](https://github.com/tim-vandecasteele/grape-swagger/pull/142), [#143](https://github.com/tim-vandecasteele/grape-swagger/pull/143): Added support for kramdown, redcarpet and custom formatters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
|
||||
* Your Contribution Here
|
||||
|
||||
#### Fixes
|
||||
|
||||
* [#105](https://github.com/tim-vandecasteele/grape-swagger/pull/105): Fixed compatibility with Swagger-UI - [@CraigCottingham](https://github.com/CraigCottingham).
|
||||
* [#87](https://github.com/tim-vandecasteele/grape-swagger/pull/87): Fixed mapping of `default` to `defaultValue` - [@m-o-e](https://github.com/m-o-e).
|
||||
* [#127](https://github.com/tim-vandecasteele/grape-swagger/pull/127): Fixed `undefined method 'reject' for nil:NilClass` error for an invalid route, now returning 404 Not Found - [@dblock](https://github.com/dblock).
|
||||
* [#135](https://github.com/tim-vandecasteele/grape-swagger/pull/135): Fixed model inclusion in models with aliased references - [@cdarne](https://github.com/cdarne).
|
||||
|
||||
#### Dev
|
||||
|
||||
* [#126](https://github.com/tim-vandecasteele/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
|
||||
* Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
|
||||
* Added `GrapeSwagger::VERSION` - [@dblock](https://github.com/dblock).
|
||||
* Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
|
||||
|
||||
### 0.7.2 (February 6, 2014)
|
||||
|
||||
|
|
|
|||
22
README.md
22
README.md
|
|
@ -19,6 +19,10 @@ Add to your Gemfile:
|
|||
|
||||
```gem 'grape-swagger'```
|
||||
|
||||
## Upgrade
|
||||
|
||||
Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
|
||||
|
||||
## Usage
|
||||
|
||||
Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc.json'. See [test/api.rb](test/api.rb) for a simple demo.
|
||||
|
|
@ -212,7 +216,7 @@ module API
|
|||
type = current_user.admin? ? :full : :default
|
||||
present statuses, with: API::Entities::Status, type: type
|
||||
end
|
||||
|
||||
|
||||
desc 'Creates a new status', entity: API::Entities::Status, params: API::Entities::Status.documentation
|
||||
post '/statuses' do
|
||||
...
|
||||
|
|
@ -290,7 +294,7 @@ Grape-swagger uses adapters for several markdown formatters. It includes adapter
|
|||
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.
|
||||
|
||||
|
||||
### Kramdown
|
||||
### Kramdown
|
||||
If you want to use kramdown as markdown formatter, you need to add kramdown to your gemfile.
|
||||
|
||||
```
|
||||
|
|
@ -302,11 +306,11 @@ Configure your api documentation route with:
|
|||
|
||||
``` ruby
|
||||
add_swagger_documentation(
|
||||
markdown: GrapeSwagger::Markdown::KramdownAdapter.new
|
||||
markdown: GrapeSwagger::Markdown::KramdownAdapter
|
||||
)
|
||||
```
|
||||
|
||||
Finally you can write endpoint descriptions the with markdown enabled.
|
||||
Finally you can write endpoint descriptions the with markdown enabled.
|
||||
|
||||
``` ruby
|
||||
desc "Reserve a virgin in heaven", {
|
||||
|
|
@ -334,7 +338,7 @@ As alternative you can use [redcarpet](https://github.com/vmg/redcarpet) as form
|
|||
|
||||
```
|
||||
gem 'redcarpet'
|
||||
gem 'rouge'
|
||||
gem 'rouge'
|
||||
```
|
||||
|
||||
Configure your api documentation route with:
|
||||
|
|
@ -352,21 +356,21 @@ You can also add your custom adapter for your favourite markdown formatter, as l
|
|||
|
||||
``` ruby
|
||||
module API
|
||||
|
||||
|
||||
class MySuperbMarkdownFormatterAdapter
|
||||
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: MySuperbMarkdownFormatterAdapter.new { no_links: true }
|
||||
add_swagger_documentation markdown: MySuperbMarkdownFormatterAdapter, { no_links: true }
|
||||
end
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,47 @@
|
|||
Upgrading Grape-swagger
|
||||
=======================
|
||||
|
||||
### Upgrading to >= 0.8.0
|
||||
|
||||
#### Changes in Configuration
|
||||
|
||||
The following options have been added, removed or have been changed in the grape-swagger interface:
|
||||
|
||||
* `markdown: true/false` => `markdown: GrapeSwagger::Markdown::KramdownAdapter`
|
||||
|
||||
#### Markdown
|
||||
|
||||
You can now configure a markdown adapter. This was originally changed because of performance issues with Kramdown and the `markdown` option no longer takes a boolean argument. Built-in adapters include Kramdown and Redcarpet.
|
||||
|
||||
##### Kramdown
|
||||
|
||||
To configure the markdown with Kramdown, add the kramdown gem to your Gemfile:
|
||||
|
||||
`gem 'kramdown'`
|
||||
|
||||
Configure grape-swagger as follows:
|
||||
|
||||
```ruby
|
||||
add_swagger_documentation (
|
||||
markdown: GrapeSwagger::Markdown::KramdownAdapter
|
||||
)
|
||||
```
|
||||
|
||||
#### Redcarpet
|
||||
|
||||
To configure markdown with Redcarpet, add the redcarpet and the rouge gem to your Gemfile. Note that Redcarpet does not work with JRuby.
|
||||
|
||||
```ruby
|
||||
gem 'redcarpet'
|
||||
gem 'rouge'
|
||||
```
|
||||
|
||||
Configure grape-swagger as follows:
|
||||
|
||||
```ruby
|
||||
add_swagger_documentation (
|
||||
markdown: GrapeSwagger::Markdown::RedcarpetAdapter
|
||||
)
|
||||
```
|
||||
|
||||
See [#142](https://github.com/tim-vandecasteele/grape-swagger/pull/142) and documentation section [Markdown in Notes](https://github.com/tim-vandecasteele/grape-swagger#markdown-in-notes) for more information.
|
||||
|
|
@ -8,6 +8,7 @@ module GrapeSwagger
|
|||
# The adapters are responsible of loading the required markdown dependencies and throw errors.
|
||||
###
|
||||
def initialize(adapter)
|
||||
adapter = adapter.new if adapter.is_a?(Class)
|
||||
fail(ArgumentError, "The configured markdown adapter should implement the method #{ :markdown }") unless adapter.respond_to? :markdown
|
||||
@adapter = adapter
|
||||
end
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
module GrapeSwagger
|
||||
VERSION = '0.7.2'
|
||||
VERSION = '0.8.0'
|
||||
end
|
||||
|
|
|
|||
|
|
@ -394,18 +394,46 @@ describe 'options: ' do
|
|||
end
|
||||
end
|
||||
|
||||
subject do
|
||||
Class.new(Grape::API) do
|
||||
mount MarkDownMountedApi
|
||||
end
|
||||
end
|
||||
|
||||
def app
|
||||
SimpleApiWithMarkdown
|
||||
end
|
||||
|
||||
it 'parses markdown for a mounted-api' do
|
||||
get '/swagger_doc/something.json'
|
||||
expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
|
||||
context 'with instance' do
|
||||
before do
|
||||
subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter.new, info: { description: '_test_' }
|
||||
end
|
||||
|
||||
it 'parses markdown for a mounted-api' do
|
||||
get '/swagger_doc/something.json'
|
||||
expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
|
||||
end
|
||||
|
||||
it 'parses markdown for swagger info' do
|
||||
get '/swagger_doc.json'
|
||||
expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
|
||||
end
|
||||
end
|
||||
|
||||
it 'parses markdown for swagger info' do
|
||||
get '/swagger_doc.json'
|
||||
expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
|
||||
context 'with class' do
|
||||
before do
|
||||
subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter, info: { description: '_test_' }
|
||||
end
|
||||
|
||||
it 'parses markdown for a mounted-api' do
|
||||
get '/swagger_doc/something.json'
|
||||
expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
|
||||
end
|
||||
|
||||
it 'parses markdown for swagger info' do
|
||||
get '/swagger_doc.json'
|
||||
expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue