apipie-rails 0.0.24 → 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +1 -1
- data/.travis.yml +6 -0
- data/CHANGELOG.md +97 -0
- data/Gemfile +1 -1
- data/Gemfile.rails30 +5 -0
- data/Gemfile.rails32 +5 -0
- data/Gemfile.rails40 +5 -0
- data/Gemfile.rails41 +5 -0
- data/README.rst +126 -11
- data/apipie-rails.gemspec +1 -1
- data/app/controllers/apipie/apipies_controller.rb +3 -0
- data/app/helpers/apipie_helper.rb +9 -0
- data/app/views/apipie/apipies/_metadata.erb +1 -0
- data/app/views/apipie/apipies/_method_detail.erb +46 -0
- data/app/views/apipie/apipies/_params.html.erb +12 -0
- data/app/views/apipie/apipies/_params_plain.html.erb +4 -0
- data/app/views/apipie/apipies/apipie_checksum.json.erb +1 -0
- data/app/views/apipie/apipies/method.html.erb +1 -37
- data/app/views/apipie/apipies/plain.html.erb +1 -0
- data/app/views/apipie/apipies/resource.html.erb +6 -37
- data/app/views/apipie/apipies/static.html.erb +1 -0
- data/lib/apipie/application.rb +16 -2
- data/lib/apipie/configuration.rb +8 -2
- data/lib/apipie/dsl_definition.rb +25 -6
- data/lib/apipie/error_description.rb +22 -10
- data/lib/apipie/extractor.rb +2 -1
- data/lib/apipie/extractor/writer.rb +8 -6
- data/lib/apipie/method_description.rb +7 -4
- data/lib/apipie/middleware/checksum_in_headers.rb +35 -0
- data/lib/apipie/param_description.rb +25 -4
- data/lib/apipie/resource_description.rb +8 -4
- data/lib/apipie/routing.rb +1 -0
- data/lib/apipie/validator.rb +71 -3
- data/lib/apipie/version.rb +1 -1
- data/lib/tasks/apipie.rake +26 -5
- data/spec/controllers/apipies_controller_spec.rb +2 -0
- data/spec/controllers/concerns_controller_spec.rb +1 -1
- data/spec/controllers/users_controller_spec.rb +130 -19
- data/spec/dummy/app/controllers/api/v1/architectures_controller.rb +1 -0
- data/spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb +22 -20
- data/spec/dummy/app/controllers/concerns/sample_controller.rb +32 -30
- data/spec/dummy/app/controllers/users_controller.rb +18 -5
- data/spec/lib/method_description_spec.rb +22 -0
- data/spec/lib/param_description_spec.rb +77 -0
- data/spec/lib/rake_spec.rb +68 -0
- data/spec/lib/resource_description_spec.rb +18 -0
- data/spec/lib/validator_spec.rb +9 -0
- data/spec/spec_helper.rb +2 -1
- data/spec/support/rake.rb +21 -0
- metadata +20 -7
- data/CHANGELOG +0 -72
data/.gitignore
CHANGED
data/.travis.yml
CHANGED
data/CHANGELOG.md
ADDED
@@ -0,0 +1,97 @@
|
|
1
|
+
===========
|
2
|
+
Changelog
|
3
|
+
===========
|
4
|
+
|
5
|
+
v0.1.0
|
6
|
+
------
|
7
|
+
|
8
|
+
* middleware for computing Apipie checksum for [dynamic bindings](https://github.com/Apipie/apipie-bindings) [#215](https://github.com/Apipie/apipie-rails/pull/215) [@mbacovsky][]
|
9
|
+
* `api_base_url` inherited properly [#214](https://github.com/Apipie/apipie-rails/pull/214) [@mbacovsky][]
|
10
|
+
* ability to hide specific parameters [#208](https://github.com/Apipie/apipie-rails/pull/208) [@nathanhoel][]
|
11
|
+
* fix for SafeYAML compatibility [#207](https://github.com/Apipie/apipie-rails/pull/207) [@pivotalshiny][]
|
12
|
+
* option to show all examples in the documentation [#203](https://github.com/Apipie/apipie-rails/pull/203) [@pivotalshiny][]
|
13
|
+
* support for array of hashes validation [#189](https://github.com/Apipie/apipie-rails/pull/189) [@mtparet][]
|
14
|
+
* support for saving the values based on documentation into `@api_params` variable [#188](https://github.com/Apipie/apipie-rails/pull/188) [@mtparet][]
|
15
|
+
* support for json generated from rake task `rake apipie:static_json` [#186](https://github.com/Apipie/apipie-rails/pull/186) [@mtparet][]
|
16
|
+
* fix `undefined method 'has_key?' for nil:NilClass` when validating Hash against non-hash value [#185](https://github.com/Apipie/apipie-rails/pull/185) [@mtparet][]
|
17
|
+
* fix NoMethorError when validating Hash against non-hash value [#183](https://github.com/Apipie/apipie-rails/pull/183) [@nathanhoel][]
|
18
|
+
* support for metadata for params [#181](https://github.com/Apipie/apipie-rails/pull/181) [@tstrachota][]
|
19
|
+
* fix camelization of class names [#170](https://github.com/Apipie/apipie-rails/pull/170) [@yonpols][]
|
20
|
+
* new array class validator [#169](https://github.com/Apipie/apipie-rails/pull/169) [@mkrajewski][]
|
21
|
+
|
22
|
+
v0.0.24
|
23
|
+
-------
|
24
|
+
|
25
|
+
* fix DOS vulnerability for running in production without use_cache
|
26
|
+
* ability to load descriptions from external files
|
27
|
+
* improved examples extractor
|
28
|
+
* fixed deprecation warnings in Rails 4
|
29
|
+
* using StandardError instead of Exception for errors
|
30
|
+
|
31
|
+
v0.0.23
|
32
|
+
-------
|
33
|
+
|
34
|
+
* fix exceptions on unknown validator
|
35
|
+
* fix concerns substitution in parameters
|
36
|
+
* possibility to authenticate the API doc
|
37
|
+
* support for array in api_controllers_matcher
|
38
|
+
|
39
|
+
v0.0.22
|
40
|
+
-------
|
41
|
+
|
42
|
+
* fix "named_resources" option
|
43
|
+
* fix generating static files when concerns used
|
44
|
+
|
45
|
+
v0.0.21
|
46
|
+
-------
|
47
|
+
|
48
|
+
* fix RDoc 4.0 compatibility issue
|
49
|
+
* ``validate_value`` and ``validate_presence`` options for better
|
50
|
+
validation granularity
|
51
|
+
|
52
|
+
v0.0.20
|
53
|
+
-------
|
54
|
+
|
55
|
+
* namespaced resources - prevent collisions when one resource defined
|
56
|
+
in more modules
|
57
|
+
* ``Apipie::DSL::Concern`` for being able to use the DSL in module
|
58
|
+
that is included into controllers
|
59
|
+
|
60
|
+
v0.0.19
|
61
|
+
-------
|
62
|
+
|
63
|
+
* fix examples recording when resource_id is set
|
64
|
+
* use safe_yaml for loading examples file when available
|
65
|
+
|
66
|
+
v0.0.18
|
67
|
+
-------
|
68
|
+
|
69
|
+
* ``param_group`` and ``def_param_group`` keywords
|
70
|
+
* ``:action_aware`` options for reusing param groups for create/update actions
|
71
|
+
|
72
|
+
v0.0.17
|
73
|
+
-------
|
74
|
+
|
75
|
+
* support for multiple see links at action and ability to provide
|
76
|
+
description of see links
|
77
|
+
|
78
|
+
v0.0.16
|
79
|
+
-------
|
80
|
+
|
81
|
+
* Fix getting started being rendered even when documentation was available
|
82
|
+
|
83
|
+
v0.0.15
|
84
|
+
-------
|
85
|
+
|
86
|
+
* Fix case when there is no documentation yet: with link to how to
|
87
|
+
start
|
88
|
+
* Fix handling bad requests when cache is on
|
89
|
+
* Fix params extractor in case there is already some documentation
|
90
|
+
|
91
|
+
[@mbacovsky]: https://github.com/mbacovsky
|
92
|
+
[@tstrachota]: https://github.com/tstrachota
|
93
|
+
[@nathanhoel]: https://github.com/nathanhoel
|
94
|
+
[@pivotalshiny]: https://github.com/pivotalshiny
|
95
|
+
[@mtparet]: https://github.com/mtparet
|
96
|
+
[@yonpols]: https://github.com/yonpols
|
97
|
+
[@mkrajewski]: https://github.com/mkrajewski
|
data/Gemfile
CHANGED
data/Gemfile.rails30
ADDED
data/Gemfile.rails32
ADDED
data/Gemfile.rails40
ADDED
data/Gemfile.rails41
ADDED
data/README.rst
CHANGED
@@ -2,11 +2,13 @@
|
|
2
2
|
API Documentation Tool
|
3
3
|
========================
|
4
4
|
|
5
|
-
.. image:: https://travis-ci.org/
|
6
|
-
:target: https://travis-ci.org/
|
5
|
+
.. image:: https://travis-ci.org/Apipie/apipie-rails.png?branch=master
|
6
|
+
:target: https://travis-ci.org/Apipie/apipie-rails
|
7
|
+
.. image:: https://codeclimate.com/github/Apipie/apipie-rails.png
|
8
|
+
:target: https://codeclimate.com/github/Apipie/apipie-rails
|
7
9
|
|
8
10
|
Apipie-rails is a DSL and Rails engine for documenting you RESTful
|
9
|
-
API. Instead of traditional use of ``#comments``, Apipie
|
11
|
+
API. Instead of traditional use of ``#comments``, Apipie lets you
|
10
12
|
describe the code by code. This brings advantages like:
|
11
13
|
|
12
14
|
* no need to learn yet another syntax, you already know Ruby, right?
|
@@ -32,7 +34,7 @@ The easiest way to get Apipie up and running with your app is:
|
|
32
34
|
$ rails g apipie:install
|
33
35
|
|
34
36
|
Now you can start documenting your resources and actions (see
|
35
|
-
`DSL Reference`_ for more info:
|
37
|
+
`DSL Reference`_ for more info):
|
36
38
|
|
37
39
|
.. code:: ruby
|
38
40
|
|
@@ -65,7 +67,7 @@ Authors
|
|
65
67
|
Contributors
|
66
68
|
------------
|
67
69
|
|
68
|
-
See `Contributors page <https://github.com/
|
70
|
+
See `Contributors page <https://github.com/Apipie/apipie-rails/graphs/contributors>`_. Special thanks to all of them!
|
69
71
|
|
70
72
|
License
|
71
73
|
-------
|
@@ -125,6 +127,9 @@ error
|
|
125
127
|
app_info
|
126
128
|
In case of versioning, this sets app info description on per_version basis.
|
127
129
|
|
130
|
+
meta
|
131
|
+
Hash or array with custom metadata.
|
132
|
+
|
128
133
|
Example:
|
129
134
|
~~~~~~~~
|
130
135
|
|
@@ -140,7 +145,8 @@ Example:
|
|
140
145
|
end
|
141
146
|
api_version "development"
|
142
147
|
error 404, "Missing"
|
143
|
-
error 500, "Server crashed for some <%= reason %>"
|
148
|
+
error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
|
149
|
+
meta :author => {:name => 'John', :surname => 'Doe'}
|
144
150
|
description <<-EOS
|
145
151
|
== Long description
|
146
152
|
Example resource for rest api documentation
|
@@ -206,6 +212,9 @@ see
|
|
206
212
|
Provide reference to another method, this has to be string with
|
207
213
|
controller_name#method_name.
|
208
214
|
|
215
|
+
meta
|
216
|
+
Hash or array with custom metadata.
|
217
|
+
|
209
218
|
Example:
|
210
219
|
~~~~~~~~
|
211
220
|
|
@@ -213,7 +222,7 @@ Example:
|
|
213
222
|
|
214
223
|
api :GET, "/users/:id", "Show user profile"
|
215
224
|
error :code => 401, :desc => "Unauthorized"
|
216
|
-
error :code => 404, :desc => "Not Found"
|
225
|
+
error :code => 404, :desc => "Not Found", :meta => {:anything => "you can think of"}
|
217
226
|
param :session, String, :desc => "user is logged in", :required => true
|
218
227
|
param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
|
219
228
|
param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
|
@@ -221,8 +230,10 @@ Example:
|
|
221
230
|
param :proc_param, lambda { |val|
|
222
231
|
val == "param value" ? true : "The only good value is 'param value'."
|
223
232
|
}, :desc => "proc validator"
|
233
|
+
param :param_with_metadata, String, :desc => "", :meta => [:your, :custom, :metadata]
|
224
234
|
description "method description"
|
225
235
|
formats ['json', 'jsonp', 'xml']
|
236
|
+
meta :message => "Some very important info"
|
226
237
|
example " 'user': {...} "
|
227
238
|
see "users#showme", "link description"
|
228
239
|
see :link => "users#update", :desc => "another link description"
|
@@ -252,6 +263,15 @@ required
|
|
252
263
|
allow_nil
|
253
264
|
Set true is ``nil`` can be passed for this param.
|
254
265
|
|
266
|
+
as
|
267
|
+
Use by the processing functionality to change the name of a key params.
|
268
|
+
|
269
|
+
meta
|
270
|
+
Hash or array with custom metadata.
|
271
|
+
|
272
|
+
show
|
273
|
+
Parameter is hidden from documentation when set to false (true by default)
|
274
|
+
|
255
275
|
Example:
|
256
276
|
~~~~~~~~
|
257
277
|
|
@@ -261,6 +281,7 @@ Example:
|
|
261
281
|
param :username, String, :desc => "Username for login", :required => true
|
262
282
|
param :password, String, :desc => "Password for login", :required => true
|
263
283
|
param :membership, ["standard","premium"], :desc => "User membership"
|
284
|
+
param :admin_override, String, :desc => "Not shown in documentation", :show => false
|
264
285
|
end
|
265
286
|
def create
|
266
287
|
#...
|
@@ -485,6 +506,10 @@ validate_value
|
|
485
506
|
validate_presence
|
486
507
|
Check the params presence against the documentation.
|
487
508
|
|
509
|
+
process_params
|
510
|
+
Process and extract parameter defined from the params of the request
|
511
|
+
to the api_params variable
|
512
|
+
|
488
513
|
app_info
|
489
514
|
Application long description.
|
490
515
|
|
@@ -498,7 +523,7 @@ markup
|
|
498
523
|
You can choose markup language for descriptions of your application,
|
499
524
|
resources and methods. RDoc is the default but you can choose from
|
500
525
|
Apipie::Markup::Markdown.new or Apipie::Markup::Textile.new.
|
501
|
-
In order to use Markdown you need
|
526
|
+
In order to use Markdown you need Maruku gem and for Textile you
|
502
527
|
need RedCloth. Add those to your gemfile and run bundle if you
|
503
528
|
want to use them. You can also add any other markup language
|
504
529
|
processor.
|
@@ -521,6 +546,9 @@ authenticate
|
|
521
546
|
Pass a proc in order to authenticate user. Pass nil for
|
522
547
|
no authentication (by default).
|
523
548
|
|
549
|
+
show_all_examples
|
550
|
+
Set this to true to set show_in_doc=1 in all recorded examples
|
551
|
+
|
524
552
|
Example:
|
525
553
|
|
526
554
|
.. code:: ruby
|
@@ -532,7 +560,7 @@ Example:
|
|
532
560
|
config.api_base_url = "/api"
|
533
561
|
config.validate = false
|
534
562
|
config.markup = Apipie::Markup::Markdown.new
|
535
|
-
config.reload_controllers =
|
563
|
+
config.reload_controllers = Rails.env.development?
|
536
564
|
config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
|
537
565
|
config.app_info = "
|
538
566
|
This is where you can inform user about your application and API
|
@@ -541,10 +569,43 @@ Example:
|
|
541
569
|
config.authenticate = Proc.new do
|
542
570
|
authenticate_or_request_with_http_basic do |username, password|
|
543
571
|
username == "test" && password == "supersecretpassword"
|
544
|
-
end
|
572
|
+
end
|
545
573
|
end
|
546
574
|
end
|
547
575
|
|
576
|
+
checksum_path
|
577
|
+
Used in ChecksumInHeaders middleware (see `JSON checksums`_ for more info). It contains path prefix(es) where the header with checksum is added. If set to nil, checksum is added in headers in every response. e.g. ``%w[/api /apipie]``
|
578
|
+
|
579
|
+
update_checksum
|
580
|
+
If set to true, the checksum is recalculated with every documentation_reload call
|
581
|
+
|
582
|
+
============
|
583
|
+
Processing
|
584
|
+
============
|
585
|
+
|
586
|
+
The goal is to extract and pre process parameters of the request.
|
587
|
+
|
588
|
+
For example Rails, by default, transforms empty array to nil value,
|
589
|
+
you want perhaps to transform it again to an empty array. Or you
|
590
|
+
want to support an enumeration type (comma separated values) and
|
591
|
+
you want automatically transform this string to an array.
|
592
|
+
|
593
|
+
To use it, set processing_value configuration variable to true.
|
594
|
+
In your action, use api_params variable instead of params.
|
595
|
+
|
596
|
+
Also by using `as` you can separate your API parameters
|
597
|
+
names from the names you are using inside your code.
|
598
|
+
|
599
|
+
To implement it, you just have to write a process_value
|
600
|
+
function in your validator:
|
601
|
+
|
602
|
+
For an enumeration type:
|
603
|
+
|
604
|
+
.. code:: ruby
|
605
|
+
|
606
|
+
def process_value(value)
|
607
|
+
value ? value.split(',') : []
|
608
|
+
end
|
548
609
|
|
549
610
|
============
|
550
611
|
Validators
|
@@ -637,6 +698,20 @@ override parameters described on resource level.
|
|
637
698
|
#...
|
638
699
|
end
|
639
700
|
|
701
|
+
NestedValidator
|
702
|
+
-------------
|
703
|
+
|
704
|
+
You can describe nested parameters in depth if you provide a block with
|
705
|
+
description of nested values.
|
706
|
+
|
707
|
+
.. code:: ruby
|
708
|
+
|
709
|
+
param :comments, Array, :desc => "User comments" do
|
710
|
+
param :name, String, :desc => "Name of the comment", :required => true
|
711
|
+
param :comment, String, :desc => "Full comment", :required => true
|
712
|
+
end
|
713
|
+
|
714
|
+
|
640
715
|
|
641
716
|
Adding custom validator
|
642
717
|
-----------------------
|
@@ -797,13 +872,52 @@ This will copy the Apipie views to ``app/views/apipie/apipies`` and
|
|
797
872
|
To generate a static version of documentation (perhaps to put it on
|
798
873
|
project site or something) run ``rake apipie:static`` task. It will
|
799
874
|
create set of html files (multi-pages, single-page, plain) in your doc
|
800
|
-
directory.
|
875
|
+
directory. If you prefer a json version run ``rake apipie:static_json``.
|
876
|
+
By default the documentation for default API version is
|
801
877
|
used, you can specify the version with ``rake apipie:static[2.0]``
|
802
878
|
|
803
879
|
When you want to avoid any unnecessary computation in production mode,
|
804
880
|
you can generate a cache with ``rake apipie:cache`` and configure the
|
805
881
|
app to use it in production with ``config.use_cache = Rails.env.production?``
|
806
882
|
|
883
|
+
===================
|
884
|
+
JSON checksums
|
885
|
+
===================
|
886
|
+
|
887
|
+
If the API client needs to be sure that the JSON didn't changed, add
|
888
|
+
the ``ApipieChecksumInHeaders`` middleware in your rails app.
|
889
|
+
It can add checksum of entiere JSON document in the response headers.
|
890
|
+
|
891
|
+
.. code::
|
892
|
+
|
893
|
+
"Apipie-Checksum"=>"fb81460e7f4e78d059f826624bdf9504"
|
894
|
+
|
895
|
+
`Apipie bindings <https://github.com/Apipie/apipie-bindings>`_ uses this feature to refresh its JSON cache.
|
896
|
+
|
897
|
+
To set it up add the following to your ``application.rb``
|
898
|
+
|
899
|
+
.. code::
|
900
|
+
|
901
|
+
require 'apipie/middleware/checksum_in_headers'
|
902
|
+
# Add JSON checksum in headers for smarter caching
|
903
|
+
config.middleware.use "Apipie::Middleware::ChecksumInHeaders"
|
904
|
+
|
905
|
+
And in your apipie initializer allow checksum calculation
|
906
|
+
|
907
|
+
.. code::
|
908
|
+
|
909
|
+
Apipie.configuration.update_checksum = true
|
910
|
+
|
911
|
+
and make sure your documentation is loaded.
|
912
|
+
|
913
|
+
.. code::
|
914
|
+
|
915
|
+
Apipie.reload_documentation
|
916
|
+
|
917
|
+
By default the header is added to responses for ``config.doc_base_url`` and ``/api``.
|
918
|
+
It can be changed in configuration (see `Configuration Reference`_ for details).
|
919
|
+
|
920
|
+
|
807
921
|
===================
|
808
922
|
Tests Integration
|
809
923
|
===================
|
@@ -929,6 +1043,7 @@ provided it uses Apipie as a backend.
|
|
929
1043
|
|
930
1044
|
And if you write one on your own, don't hesitate to share it with us!
|
931
1045
|
|
1046
|
+
|
932
1047
|
====================
|
933
1048
|
Disqus Integration
|
934
1049
|
====================
|
data/apipie-rails.gemspec
CHANGED
@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
|
|
19
19
|
s.add_dependency "rails", ">= 3.0.10"
|
20
20
|
s.add_development_dependency "rspec-rails"
|
21
21
|
s.add_development_dependency "sqlite3"
|
22
|
-
s.add_development_dependency "minitest"
|
22
|
+
s.add_development_dependency "minitest"
|
23
23
|
s.add_development_dependency "maruku"
|
24
24
|
s.add_development_dependency "RedCloth"
|
25
25
|
s.add_development_dependency "rake"
|