apipie-dsl 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/README.md +485 -0
  4. data/app/controllers/apipie_dsl/apipie_dsls_controller.rb +190 -0
  5. data/app/helpers/apipie_dsl_helper.rb +110 -0
  6. data/app/public/apipie_dsl/javascripts/apipie_dsl.js +6 -0
  7. data/app/public/apipie_dsl/javascripts/bundled/bootstrap-collapse.js +138 -0
  8. data/app/public/apipie_dsl/javascripts/bundled/bootstrap.js +1726 -0
  9. data/app/public/apipie_dsl/javascripts/bundled/jquery.js +5 -0
  10. data/app/public/apipie_dsl/javascripts/bundled/prettify.js +28 -0
  11. data/app/public/apipie_dsl/stylesheets/application.css +7 -0
  12. data/app/public/apipie_dsl/stylesheets/bundled/bootstrap-responsive.min.css +12 -0
  13. data/app/public/apipie_dsl/stylesheets/bundled/bootstrap.min.css +689 -0
  14. data/app/public/apipie_dsl/stylesheets/bundled/prettify.css +30 -0
  15. data/app/views/apipie_dsl/apipie_dsls/_index_class_meth.erb +11 -0
  16. data/app/views/apipie_dsl/apipie_dsls/_index_class_prop.erb +13 -0
  17. data/app/views/apipie_dsl/apipie_dsls/_languages.erb +6 -0
  18. data/app/views/apipie_dsl/apipie_dsls/_metadata.erb +1 -0
  19. data/app/views/apipie_dsl/apipie_dsls/_method.erb +34 -0
  20. data/app/views/apipie_dsl/apipie_dsls/_method_detail.erb +58 -0
  21. data/app/views/apipie_dsl/apipie_dsls/_params.html.erb +47 -0
  22. data/app/views/apipie_dsl/apipie_dsls/_params_plain.html.erb +19 -0
  23. data/app/views/apipie_dsl/apipie_dsls/_property.erb +24 -0
  24. data/app/views/apipie_dsl/apipie_dsls/_property_detail.erb +35 -0
  25. data/app/views/apipie_dsl/apipie_dsls/_raises.html.erb +23 -0
  26. data/app/views/apipie_dsl/apipie_dsls/_returns.html.erb +53 -0
  27. data/app/views/apipie_dsl/apipie_dsls/apipie_dsl_404.html.erb +17 -0
  28. data/app/views/apipie_dsl/apipie_dsls/class.html.erb +75 -0
  29. data/app/views/apipie_dsl/apipie_dsls/custom_help.html.erb +10 -0
  30. data/app/views/apipie_dsl/apipie_dsls/getting_started.html.erb +4 -0
  31. data/app/views/apipie_dsl/apipie_dsls/index.html.erb +72 -0
  32. data/app/views/apipie_dsl/apipie_dsls/method.html.erb +52 -0
  33. data/app/views/apipie_dsl/apipie_dsls/plain.html.erb +116 -0
  34. data/app/views/apipie_dsl/apipie_dsls/static.html.erb +158 -0
  35. data/app/views/layouts/apipie_dsl/apipie_dsl.html.erb +26 -0
  36. data/lib/apipie-dsl.rb +3 -0
  37. data/lib/apipie_dsl.rb +28 -0
  38. data/lib/apipie_dsl/Rakefile +6 -0
  39. data/lib/apipie_dsl/apipie_dsl_module.rb +51 -0
  40. data/lib/apipie_dsl/application.rb +321 -0
  41. data/lib/apipie_dsl/class_description.rb +107 -0
  42. data/lib/apipie_dsl/configuration.rb +87 -0
  43. data/lib/apipie_dsl/dsl.rb +596 -0
  44. data/lib/apipie_dsl/errors.rb +68 -0
  45. data/lib/apipie_dsl/exception_description.rb +39 -0
  46. data/lib/apipie_dsl/markup.rb +41 -0
  47. data/lib/apipie_dsl/method_description.rb +112 -0
  48. data/lib/apipie_dsl/parameter_description.rb +152 -0
  49. data/lib/apipie_dsl/railtie.rb +15 -0
  50. data/lib/apipie_dsl/return_description.rb +71 -0
  51. data/lib/apipie_dsl/routing.rb +17 -0
  52. data/lib/apipie_dsl/see_description.rb +35 -0
  53. data/lib/apipie_dsl/static_dispatcher.rb +70 -0
  54. data/lib/apipie_dsl/tag_list_description.rb +11 -0
  55. data/lib/apipie_dsl/tasks/apipie_dsl/cache.rake +43 -0
  56. data/lib/apipie_dsl/tasks/apipie_dsl/static.rake +43 -0
  57. data/lib/apipie_dsl/tasks/apipie_dsl/static_json.rake +29 -0
  58. data/lib/apipie_dsl/tasks_utils.rb +137 -0
  59. data/lib/apipie_dsl/utils.rb +83 -0
  60. data/lib/apipie_dsl/validator.rb +479 -0
  61. data/lib/apipie_dsl/version.rb +5 -0
  62. data/lib/generators/apipie_dsl/install/install_generator.rb +21 -0
  63. data/lib/generators/apipie_dsl/install/templates/initializer.rb.erb +9 -0
  64. data/lib/generators/apipie_dsl/views_generator.rb +14 -0
  65. data/test/test_helper.rb +6 -0
  66. metadata +220 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: a35887dd905400d990949adfb5bd0322929bb06805e6355b4e03ab0d2ca4c816
4
+ data.tar.gz: c8a848d353d9041504d5e973486e2e1555eb75ded948e050c27e5d5f13948fe3
5
+ SHA512:
6
+ metadata.gz: e0b1c8416e26e9ee2c132a769354a33786cdc4bc7785d6779b58b5793f040b38487e3887d00f6897cfe22f7b68c5f56697a3fa26a2ba5611217f35edfdf78786
7
+ data.tar.gz: 7870fee3fde011346710c7e3bd9da7124b0eeda34439cd373f81c2424a3ebfed6c25863297f5cab402b46a05285865314f43e97ad6a61d6ca9605e728fc3de8a
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2018 Oleh Fedorenko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,485 @@
1
+ # DSL Documentation Tool
2
+
3
+ Apipie-dsl is a DSL for documenting DSLs written in Ruby. Instead of traditional
4
+ use of `#comments`, ApipieDSL lets you describe the code, through the code.
5
+
6
+ ## Getting started
7
+
8
+ The easiest way to get ApipieDSL up and running with your app is:
9
+
10
+ ```sh
11
+ echo "gem 'apipie-dsl'" >> Gemfile
12
+ bundle install
13
+ rails g apipie:install
14
+ ```
15
+
16
+ Now you can start documenting your DSLs (see
17
+ [DSL Reference](#DSL-Reference) for more info):
18
+
19
+ ```ruby
20
+ apipie :method, 'Method description' do
21
+ required :string, String, 'Required string parameter'
22
+ end
23
+ def print(string)
24
+ # ...
25
+ end
26
+ ```
27
+
28
+ # Documentation
29
+ ## Contents
30
+ - [__Configuration Reference__](#Configuration-Reference)
31
+ - [__DSL Reference__](#DSL-Reference)
32
+
33
+ ### Configuration Reference
34
+
35
+ Create a configuration file (e.g. `/config/initializers/apipie-dsl.rb` for
36
+ Rails). You can set the application name, footer text, DSL and documentation
37
+ base URL and turn off validations. You can also choose your favorite markup
38
+ language for full descriptions.
39
+
40
+ - __app_name__ - Name of your application; used in breadcrumbs navigation.
41
+
42
+ - __app_info__ - Application long description.
43
+
44
+ - __copyright__ - Copyright information (shown in page footer).
45
+
46
+ - __doc_base_url__ - Documentation frontend base url.
47
+
48
+ - __default_version__ - Default DSL version to be used (1.0 by default).
49
+
50
+ - __sections__ - What sections should the HTML documentation have
51
+ ([:all] by default).
52
+
53
+ - __validate__ - Parameters validation is turned off when set to false. When
54
+ set to `:explicitly`, you must do the parameters validation yourself.
55
+ When set to `:implicitly` (or just true), your classes' methods are wrapped
56
+ with generated methods which already contain parameters validation
57
+ (`:implicitly` by default).
58
+
59
+ - __validate_value__ - Check the value of params against specified validators
60
+ (true by default).
61
+
62
+ - __dsl_classes_matchers__ - For reloading to work properly you need to
63
+ specify where your DSL classes are. Can be an array if multiple paths are
64
+ needed.
65
+
66
+ - __markup__ - You can choose markup language for descriptions of your
67
+ application, classes and methods. __RDoc__ is the default but you can
68
+ choose from `ApipieDSL::Markup::Markdown.new` or
69
+ `ApipieDSL::Markup::Textile.new`. In order to use Markdown you need
70
+ `Maruku` gem and for Textile you need `RedCloth`. Add those to your
71
+ `Gemfile` and run bundle if you want to use them. You can also add any
72
+ other markup language processor.
73
+
74
+ - __ignored__ - An array of class names (strings) (might include methods as
75
+ well) to be ignored when generating the documentation (e.g.
76
+ `%w[DSL::Output DSL::HTML#tag]`).
77
+
78
+ - __class_full_names__ - Use class paths instead of class names as class id.
79
+ This prevents same named classes overwriting each other (`true` by default).
80
+
81
+ - __link_extension__ - The extension to use for DSL pages ('.html' by
82
+ default). Link extensions in static DSL docs cannot be changed from '.html'.
83
+
84
+ - __languages__ - List of languages the DSL documentation should be
85
+ translated into. Empty by default.
86
+
87
+ - __default_locale__ - Locale used for generating documentation when no
88
+ specific locale is set. Set to 'en' by default.
89
+
90
+ - __locale__ - Pass locale setter/getter.
91
+ ```ruby
92
+ config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
93
+ ```
94
+ - __translate__ - Pass proc to translate strings using the localization
95
+ library your project uses. For example see [Localization](#Localization).
96
+
97
+ - __help_layout__ - Pass path to a html with custom help section if needed.
98
+
99
+ #### Example:
100
+ ```ruby
101
+ ApipieDSL.configure do |config|
102
+ config.app_name = "Test app"
103
+ config.copyright = "© 2019 Oleh Fedorenko"
104
+ config.doc_base_url = "/apipie-dsl"
105
+ config.validate = false
106
+ config.markup = ApipieDSL::Markup::Markdown.new
107
+ config.dsl_controllers_matchers = [
108
+ "#{File.dirname(__dir__)}/dsl_example/common.rb",
109
+ "#{File.dirname(__dir__)}/dsl_example/dsl.rb"
110
+ ]
111
+ config.app_info["1.0"] = "
112
+ This is where you can inform user about your application and DSL
113
+ in general.
114
+ "
115
+ config.sections = %i[all additional]
116
+ end
117
+ ```
118
+ ### DSL Reference
119
+
120
+ #### Common Description
121
+
122
+ - __short__ (also __short_description__) - Short description of the class
123
+ (it's shown on both the list of classes, and class details).
124
+
125
+ - __desc__ (also __description__ and __full_description__)
126
+ Full description of the class (shown only in class details).
127
+
128
+ - __dsl_versions__ (also __dsl_version__)
129
+ What versions does the class define the methods (see
130
+ [Versioning](#Versioning) for details).
131
+
132
+ - __meta__ - Hash or array with custom metadata.
133
+
134
+ - __deprecated__ - Boolean value indicating if the class is marked as
135
+ deprecated (false by default).
136
+
137
+ - __show__ - Class/method is hidden from documentation when set to false
138
+ (true by default).
139
+
140
+ #### Class/Module Description
141
+
142
+ Describe your class via:
143
+ ```ruby
144
+ apipie :class do
145
+ # ...
146
+ end
147
+ ```
148
+
149
+ Inheritance is supported, so you can specify common params for group of classes
150
+ in their parent class.
151
+
152
+ The following keywords are available (all are optional):
153
+ - __name__ - Custom class name (in case if you want to explicitly save full
154
+ class name e.g. ParentModule::Class)
155
+
156
+ - __refs__/__referenced_on__ - Which references should the class understand
157
+ to be linked in the documentation (e.g. if the class is mentioned as return
158
+ value of a method, then the value will be linked with the class).
159
+
160
+ - __sections__ - In which sections the class should be shown.
161
+
162
+ - __property__ - Object's property (could be an `attr_reader` or public
163
+ method with return value).
164
+
165
+ ##### Example:
166
+ ```ruby
167
+ apipie :class, 'Base tag' do
168
+ name 'Base::Tag'
169
+ sections only: :additional
170
+ refs 'BaseTag', 'Base::Tag', 'Tag'
171
+ dsl_version 'development'
172
+ meta :author => {:name => 'John', :surname => 'Doe'}
173
+ deprecated false
174
+ description <<-EOS
175
+ == Long description
176
+ Example class for dsl documentation
177
+ ...
178
+ EOS
179
+ end
180
+ ```
181
+
182
+ #### Method Description
183
+
184
+ Then describe methods available to your DSL:
185
+ ```ruby
186
+ apipie :method do
187
+ # ...
188
+ end
189
+ ```
190
+ - __param__ - Look at [Parameter description](#Parameter-description) section
191
+ for details.
192
+
193
+ - __returns__ - Look at [Response description](#Response-description) section
194
+ for details.
195
+
196
+ - __raises__ - Describe each possible error that can happen while calling this
197
+ method.
198
+
199
+ - __param_group__ - Extract parameters defined via `apipie :param_group do ...
200
+ end`
201
+
202
+ - __see__ - Provide reference to another method, this has to be a string with
203
+ `class_name#method_name`.
204
+
205
+ ##### Example:
206
+ ```ruby
207
+ apipie :method, 'Short description' do
208
+ description 'Full method description'
209
+ required :id, String, desc: 'ID for tag'
210
+ optional :type, String, desc: 'Optional type', default: ''
211
+ param :css_class, String, :desc => 'CSS class', type: :optional, default: ''
212
+ keyword :content, Hash, :desc => 'Hash with content' do
213
+ optional :text, String, 'Text string', default: 'Default text'
214
+ end
215
+ returns BaseTag
216
+ raises ArgumentError, 'String is expected'
217
+ raises ArgumentError, 'Hash is expected'
218
+ meta :message => 'Some very important info'
219
+ see 'html#tag', 'Link description'
220
+ see :link => 'html#tags', :desc => 'Another link description'
221
+ show false
222
+ end
223
+ def tag(id, type = '', css_class = '', content: { text: 'Default text' })
224
+ #...
225
+ end
226
+ ```
227
+ #### Parameter Description
228
+
229
+ Use `param` to describe every possible parameter. You can use the Hash validator
230
+ in conjunction with a block given to the param method to describe nested
231
+ parameters.
232
+
233
+ - __name__- The first argument is the parameter name as a symbol.
234
+
235
+ - __validator__ - Second parameter is the parameter validator, choose one
236
+ from section [Validators](#Validators).
237
+
238
+ - __desc__ - Parameter description.
239
+
240
+ - __required__ Set this true/false to make it required/optional. Default is
241
+ true.
242
+
243
+ ##### Example:
244
+ ```ruby
245
+ param :user, Hash, :desc => 'User info' do
246
+ param :username, String, desc: 'Username for login', required: true
247
+ param :password, String, desc: 'Password for login', required: true
248
+ param :membership, ['standard','premium'], desc: 'User membership'
249
+ param :admin_override, String, desc: 'Not shown in documentation', show: false
250
+ end
251
+ def create
252
+ #...
253
+ end
254
+ ```
255
+ #### DRY with param_group
256
+
257
+ Often, params occur together in more methods. These params can be extracted
258
+ with `def_param_group` and `param_group` keywords.
259
+
260
+ The definition is looked up in the scope of the class. If the
261
+ group is defined in a different class, it might be referenced by
262
+ specifying the second argument.
263
+
264
+ ##### Example:
265
+ ```ruby
266
+ # v1/users_class.rb
267
+ def_param_group :address do
268
+ param :street, String
269
+ param :number, Integer
270
+ param :zip, String
271
+ end
272
+
273
+ def_param_group :user do
274
+ param :user, Hash do
275
+ param :name, String, 'Name of the user'
276
+ param_group :address
277
+ end
278
+ end
279
+
280
+ apipie :method, 'Create an user' do
281
+ param_group :user
282
+ end
283
+ def create(user)
284
+ # ...
285
+ end
286
+
287
+ apipie :method, 'Update an user' do
288
+ param_group :user
289
+ end
290
+ def update(user)
291
+ # ...
292
+ end
293
+
294
+ # v2/users_class.rb
295
+ apipie :method, 'Create an user' do
296
+ param_group :user, V1::UsersClass
297
+ end
298
+ def create(user)
299
+ # ...
300
+ end
301
+ ```
302
+ #### Return Description
303
+
304
+ TODO
305
+
306
+ ##### Example:
307
+ ```ruby
308
+ # TODO
309
+ ```
310
+
311
+ ## Rails Integration
312
+
313
+ TODO
314
+
315
+ ### Validators
316
+
317
+ TODO
318
+
319
+ ### TypeValidator
320
+
321
+ Check the parameter type. Only String, Hash and Array are supported
322
+ for the sake of simplicity. Read more to find out how to add
323
+ your own validator.
324
+
325
+ ```ruby
326
+ # TODO
327
+ ```
328
+
329
+ ### RegexpValidator
330
+
331
+ Check parameter value against given regular expression.
332
+
333
+ ```ruby
334
+ param :regexp_param, /^[0-9]* years/, desc: 'regexp param'
335
+ ```
336
+
337
+ ### EnumValidator
338
+
339
+ Check if parameter value is included in the given array.
340
+
341
+ ```ruby
342
+ param :enum_param, [100, 'one', 'two', 1, 2], desc: 'enum validator'
343
+ ```
344
+
345
+ ### ProcValidator
346
+
347
+ If you need more complex validation and you know you won't reuse it, you
348
+ can use the Proc/lambda validator. Provide your own Proc, taking the value
349
+ of the parameter as the only argument. Return true if value passes validation
350
+ or return some text about what is wrong otherwise. Don't use the keyword *return*
351
+ if you provide an instance of Proc (with lambda it is ok), just use the last
352
+ statement return property of ruby.
353
+
354
+ ```ruby
355
+ param :proc_param, lambda { |val|
356
+ val == 'param value' ? true : "The only good value is 'param value'."
357
+ }, desc: 'proc validator'
358
+ ```
359
+
360
+ ### HashValidator
361
+
362
+ You can describe hash parameters in depth if you provide a block with a
363
+ description of nested values.
364
+
365
+ ```ruby
366
+ param :user, Hash, desc: 'User info' do
367
+ required :username, String, desc: 'Username for login'
368
+ required :password, String, desc: 'Password for login'
369
+ param :membership, ['standard','premium'], desc: 'User membership'
370
+ end
371
+ ```
372
+
373
+ ### NumberValidator
374
+
375
+ Check if the parameter is a positive integer number or zero.
376
+
377
+ ```ruby
378
+ required :product_id, :number, desc: 'Identifier of the product'
379
+ required :quantity, :number, desc: 'Number of products to order'
380
+ ```
381
+
382
+ ### DecimalValidator
383
+
384
+ Check if the parameter is a decimal number.
385
+
386
+ ```ruby
387
+ required :latitude, :decimal, desc: 'Geographic latitude'
388
+ required :longitude, :decimal, desc: 'Geographic longitude'
389
+ ```
390
+
391
+ ### ArrayValidator
392
+
393
+ Check if the parameter is an array.
394
+ ```ruby
395
+ required :array_param, Array, desc: 'array param'
396
+ ```
397
+
398
+ ##### Additional options
399
+
400
+ - __of__ - Specify the type of items. If not given it accepts an array of any
401
+ item type.
402
+
403
+ - __in__ - Specify an array of valid item values.
404
+
405
+ ##### Examples:
406
+
407
+ Assert `things` is an array of any items.
408
+
409
+ ```ruby
410
+ param :things, Array
411
+ ```
412
+ Assert `hits` must be an array of integer values.
413
+
414
+ ```ruby
415
+ param :hits, Array, of: Integer
416
+ ```
417
+
418
+ Assert `colors` must be an array of valid string values.
419
+
420
+ ```ruby
421
+ param :colors, Array, in: ['red', 'green', 'blue']
422
+ ```
423
+
424
+ The retrieving of valid items can be deferred until needed using a lambda. It is evaluated only once
425
+ ```ruby
426
+ param :colors, Array, in: -> { Colors.all.map(&:name) }
427
+ ```
428
+
429
+ ### NestedValidator
430
+
431
+ You can describe nested parameters in depth if you provide a block with a
432
+ description of nested values.
433
+
434
+ ```ruby
435
+ param :comments, Array, desc: 'User comments' do
436
+ required :name, String, desc: 'Name of the comment'
437
+ required :comment, String, desc: 'Full comment'
438
+ end
439
+ ```
440
+
441
+ ### Adding custom validator
442
+
443
+ TODO
444
+
445
+ ### Versioning
446
+
447
+ TODO
448
+
449
+ ### Markup
450
+
451
+ The default markup language is
452
+ [RDoc](https://rdoc.github.io/rdoc/RDoc/Markup.html). It can be changed in
453
+ the config file (`config.markup=`) to one of these:
454
+
455
+ - __Markdown__ - Use `Apipie::Markup::Markdown.new`. You need Maruku gem.
456
+
457
+ - __Textile__ - Use `Apipie::Markup::Textile.new`. You need RedCloth gem.
458
+
459
+ Or provide you own object with a `to_html(text)` method. For inspiration, this
460
+ is how Textile markup usage is implemented:
461
+
462
+ ```ruby
463
+ class Textile
464
+ def initialize
465
+ require 'RedCloth'
466
+ end
467
+
468
+ def to_html(text)
469
+ RedCloth.new(text).to_html
470
+ end
471
+ end
472
+ ```
473
+
474
+ ### Localization
475
+
476
+ TODO
477
+
478
+ ### Static files
479
+
480
+ TODO
481
+
482
+ ### Known issues
483
+ - __Circular dependency detected while autoloading constant...__
484
+ Can appear in Rails when using a non-standard class as a validator. Passing
485
+ the validator as a string (e.g. MyClass -> 'MyClass') solves the issue.