infinum / dox Goto Github PK
View Code? Open in Web Editor NEWAutomated API documentation from Rspec
License: MIT License
Automated API documentation from Rspec
License: MIT License
The JSON format of input data in the generated redoc file shown as one line string includes all request data after adding base64 data as the value of one of the params.
I run into an issue with generating documentation for next test case:
describe 'Success' do
let(:headers) { { Authorization: 'auth token' } }
let(:params) { { image: fixture_file_upload('files/image.jpeg', 'image/jpg') } }
before do
put '/api/v1/company/logo', params: params, headers: headers
end
it 'renders with updated image' do
expect(response).to be_ok
expect(response).to match_json_schema('image/update')
end
end
My config in rails_helper.rb
:
require 'dox'
...
Dox.configure do |config|
config.header_file_path = Rails.root.join('spec', 'api_doc', 'v1', 'descriptions', 'header.md')
config.desc_folder_path = Rails.root.join('spec', 'api_doc', 'v1', 'descriptions')
config.headers_whitelist = ['Accept', 'X-Refresh-Token']
end
config.after(:each, :dox) do |example|
example.metadata[:request] = request
example.metadata[:response] = response
end
The error trace:
Traceback (most recent call last):
6: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:9:in `print'
5: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:9:in `each'
4: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:10:in `block in print'
3: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:8:in `print'
2: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `print_example_request'
1: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `puts'
/Users/alexandr/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `write': "\xFF" from ASCII-8BIT to UTF-8 (Encoding::UndefinedConversionError)
As it can be seen while debugging it stumbles upon raw image data in request's body.
To avoid using shell scripts to generate html documentation.
See if we should put it somewhere or just ignore it
The documentation is pulling it from sample
Curious if this is still an active project that just hasn't needed anything, or if it's gone dormant? Doing a survey of options to document my Rails API, and key is if the project is healthy or not.
This is useful for post requests where you specify what attributes are valid, needed and their types
When documenting POST, PUT, or PATCH requests in rails 4 applications, the generated documentation includes the request body parameters into the url.
because of instance_eval
i need to extend helpers module in each action
example:
document :index do
action 'Order Index' do
extend ApiDoc::Shared
params index_params
path "/api/{version}/orders{?#{param_keys(index_params)}}"
end
end
maybe introduce something like https://github.com/ruby-grape/grape/blob/master/lib/grape/dsl/helpers.rb
Hello
Api Blueprint has Request Attributes Section:
https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-attributes-section
Also, Apiary supports MSON in request attributes description:
https://help.apiary.io/tools/interactive-documentation/
Added support of these features in my fork of dox-project:
veejar@d0f7127
When content-type
and accept
headers on request are not application/json
, e.g. they're set to application/vnd.api+json
I get a JSON::ParserError: 784: unexpected token
when trying to generate documentation.
When response returns application/vnd.api+json
in the headers, documentation can be generated.
Please use the latest version of Infinum's default changelog template and rename it to CHANGELOG.md:
Is this no longer being developed?
Only valid HTTP verbs should be permitted.
Some of our POST endpoints have a JSON body and I would like to include that in our documentation.
It seems that for the request, just the header information is grabbed. Is there support for request bodies? Could it be added?
There seems to be a bug on feature/openapi
branch โ descriptions added to action block are never rendered.
Steps to reproduce:
document :create do
action 'Create smth' do
desc 'hello'
end
end
The action will be rendered in the generated documentation, but the description is missing. I've tried to pass both inline descriptions and markdown files, but none of them were rendered.
I think the bug is in lib/dox/printers/action_printer.rb
file โ https://github.com/infinum/dox/pull/46/files#diff-87105a834429cb75e9b69541c6dc3d68. There used to be code there which handled rendering descriptions, but it was removed.
Hello
I have question related to parsing API Request Body.
https://github.com/infinum/dox/blob/master/lib/dox/entities/example.rb#L72
Why only JSON-type request is valid? My API allows RAW or JSON type parameters in requests to API. In tests I've used RAW-type and now I should to change a lot of code to use Dox.
Do you plan to add RAW-body support dependent on Content-Type header in request?
When I run rspec -f Dox::Formatter
I get:
Traceback (most recent call last):
17: from /usr/local/bundle/bin/rspec:23:in `<main>'
16: from /usr/local/bundle/bin/rspec:23:in `load'
15: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
5: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
4: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
3: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `custom_formatter'
2: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `inject'
1: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `each'
/usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `block in custom_formatter': uninitialized constant Dox (NameError)
17: from /usr/local/bundle/bin/rspec:23:in `<main>'
16: from /usr/local/bundle/bin/rspec:23:in `load'
15: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
5: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
4: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
3: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:224:in `custom_formatter'
2: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:227:in `rescue in custom_formatter'
1: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
/usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- dox/formatter (LoadError)
21: from /usr/local/bundle/bin/rspec:23:in `<main>'
20: from /usr/local/bundle/bin/rspec:23:in `load'
19: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
18: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
17: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
16: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
15: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:224:in `custom_formatter'
6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:227:in `rescue in custom_formatter'
5: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:34:in `require'
4: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:130:in `rescue in require'
3: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:130:in `require'
2: from /usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:5:in `<top (required)>'
1: from /usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:6:in `<module:Dox>'
/usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:7:in `<class:Formatter>': uninitialized constant Dox::Formatter::Forwardable (NameError)
I have this in rails_helper.rb
:
RSpec.configure do |config|
config.include FeatureMacros
config.infer_spec_type_from_file_location!
config.filter_rails_from_backtrace!
config.after(:each, :dox) do |example|
example.metadata[:request] = request
example.metadata[:response] = response
end
end
Dox.configure do |config|
config.header_file_path = Rails.root.join('spec/docs/v2/descriptions/header.md')
config.desc_folder_path = Rails.root.join('spec/docs/v2/descriptions')
config.headers_whitelist = %w[Email Password Password-Confirmation
Ahoy-Visit Ahoy-Visitor Access-Token
Token-Type Client Expiry UID Profile-ID
Birth-date Reg-Number Document]
end
Editing the gem folder and adding require 'forwardable'
in lib/dox/formatter.rb
seems to solve the problem.
Hello, I'm using rails 5.2.2 with dox 1.1.0, I'm using request specs to generate documentation.
The headers included in the documentation are only 'Accept' and 'Content-Type'.
I added this to an initializer.
Dox.configure do |config|
config.headers_whitelist = ['access-token', 'token-type', 'client', 'expiry', 'uid']
end
But this is not working, when I try and debug it and check the contents of full_headers_whitelist only shows 'Accept' and 'Content-Type'.
Am I missing something here?
Thanks
When I try to use the resource_group
method inside the document
block I get a
NoMethodError: undefined method 'resource_group' for #<Dox::DSL::Documentation:0x007fafb218fe20>
e.g inside
document :api do
resource 'Foo' do
endpoint '/foo'
group 'Foo'
end
resource_group 'bar' do
end
end
Hitting an exception on this line:
@verb = details[:action_verb] || request.method
https://github.com/infinum/dox/blob/master/lib/dox/entities/action.rb#L11
In my app, request
is a Proc
and Proc#method
expects a symbol as an argument: https://ruby-doc.org/core-2.2.0/Object.html#method-i-method
Some context:
# ./spec/requests/groups/show_spec.rb
describe %(get '/api/groups/:id'), type: :request do
include Docs::Groups::Api
let!(:path) { %(/api/groups/#{group.id}) }
let!(:user) { create(:user_with_groups) }
let!(:group) { user.groups.last }
context 'when a user is signed in' do
before { sign_in user }
before { get path }
after { sign_out user }
it 'returns http success (2xx)', :dox do
include Docs::Groups::Show
expect(response).to have_http_status(:success)
end
end
end
# ./spec/docs/groups.rb
module Docs
module Groups
extend Dox::DSL::Syntax
# define common resource data for each action
document :api do
resource 'Groups' do
endpoint '/groups'
group 'Groups'
end
end
# define data for specific action
document :index do
action 'Get groups'
end
document :show do
action 'Get a group'
end
end
end
There are only internal params for an action that we use as route default params, but do not want to show in documentation.
I would expect that using
params({})
within an action should remove all the params, but it shows the default ones (that are passed within example request) instead.
Is this expected for some reason on needs a fix?
The current ugly workaround for me is
params(Struct.new(:presence).new({}))
as the gem is using presence
internally.
Hi folks,
This is a fantastic gem!
I have a question on tagging specs to be used in documentation generation. Currently, I have it working as you mention in the readme, tagging specs with :dox
and then running the output through the Dox::Formatter.
I was wondering if we could use another tag? The reason for this is I would like to figure out how to seperate public API documentation from private, perhaps by tagging specs as public_dox
and private_dox
. I tried changing my tags in the specs to private_dox
and then reconfiguring the rails_helper.rb configuration as below, but I cannot seem to get the documentation to generate.
config.after(:each, :private_dox) do |example|
example.metadata[:request] = request
example.metadata[:response] = response
end
Does this use of different tags sound possible? And if so, any idea on what I might be missing to get this different tag working?
Also, this is how I am running the specs to produce the documentation:
bundle exec rspec spec/controllers/api/auth_controller_spec.rb -f Dox::Formatter --order defined --tag private_dox --out docs.md
Thank you for this amazing gem!
The schema option need to be added for header parameters. According to open api 3.0.0, parameters should have a schema property.
...
paths:
/post:
post:
parameters:
- in: header
name: X-username
schema:
type: string
example: user12345
Currently headers don't have schema property.
paths:
/post:
post:
parameters:
- in: header
name: X-username
example: user12345
Can you please address this issue ?
Use regular heredocs for multiline strings. Also use heredocs in printers.
When i add ['Accpet']
to headers_whitelist
this is what i get:
+ Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/x-www-form-urlencoded
grape api and request specs
How is the response picked up within rspec?
I would like to replace some response values with something generic.
Thanks for this great library! ๐
Open API Extensions are supported by some doc generators like Redoc and allow us to add branding, e.g. x-logo
. It would be great if we can add this in the Dox configuration, perhaps namespaced under extensions
or similar, for example:
Dox.configure do |config|
# ...
config.extensions['x-logo'] = {
"url": "https://example.com/logo.png",
"backgroundColor": "#ff3399"
}
# ...
end
I was able to add support for automated branding afterwards with the following script:
#!/usr/local/bin/ruby
require 'json'
docs = File.read('spec/api_doc/v1/schemas/docs.json')
docs_json = JSON.parse(docs)
docs_json['info']['x-logo'] = {
"url": "https://example.com/logo.png",
"backgroundColor": "#ff3399"
}
updated_docs = JSON.pretty_generate(docs_json)
File.write('spec/api_doc/v1/schemas/docs.json', updated_docs)
Thanks again for all your great work on this library.
it adds http:/
on the url if request has query parameters
Eventually add a config option to ignore certain headers (a blacklist), but I can live without having that option for now.
After #3 is resolved.
Right now, every example is by default included in the generated documentation, and blacklisting examples is done with :nodoc option.
This is a problem when you have a lot of "it" blocks for each action - documentation gets bloated.
This should be dropped in the new version and tests that should be documented should be whitelisted with :doc or similar option.
Example app with different usage combinations.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.