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.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +485 -0
- data/app/controllers/apipie_dsl/apipie_dsls_controller.rb +190 -0
- data/app/helpers/apipie_dsl_helper.rb +110 -0
- data/app/public/apipie_dsl/javascripts/apipie_dsl.js +6 -0
- data/app/public/apipie_dsl/javascripts/bundled/bootstrap-collapse.js +138 -0
- data/app/public/apipie_dsl/javascripts/bundled/bootstrap.js +1726 -0
- data/app/public/apipie_dsl/javascripts/bundled/jquery.js +5 -0
- data/app/public/apipie_dsl/javascripts/bundled/prettify.js +28 -0
- data/app/public/apipie_dsl/stylesheets/application.css +7 -0
- data/app/public/apipie_dsl/stylesheets/bundled/bootstrap-responsive.min.css +12 -0
- data/app/public/apipie_dsl/stylesheets/bundled/bootstrap.min.css +689 -0
- data/app/public/apipie_dsl/stylesheets/bundled/prettify.css +30 -0
- data/app/views/apipie_dsl/apipie_dsls/_index_class_meth.erb +11 -0
- data/app/views/apipie_dsl/apipie_dsls/_index_class_prop.erb +13 -0
- data/app/views/apipie_dsl/apipie_dsls/_languages.erb +6 -0
- data/app/views/apipie_dsl/apipie_dsls/_metadata.erb +1 -0
- data/app/views/apipie_dsl/apipie_dsls/_method.erb +34 -0
- data/app/views/apipie_dsl/apipie_dsls/_method_detail.erb +58 -0
- data/app/views/apipie_dsl/apipie_dsls/_params.html.erb +47 -0
- data/app/views/apipie_dsl/apipie_dsls/_params_plain.html.erb +19 -0
- data/app/views/apipie_dsl/apipie_dsls/_property.erb +24 -0
- data/app/views/apipie_dsl/apipie_dsls/_property_detail.erb +35 -0
- data/app/views/apipie_dsl/apipie_dsls/_raises.html.erb +23 -0
- data/app/views/apipie_dsl/apipie_dsls/_returns.html.erb +53 -0
- data/app/views/apipie_dsl/apipie_dsls/apipie_dsl_404.html.erb +17 -0
- data/app/views/apipie_dsl/apipie_dsls/class.html.erb +75 -0
- data/app/views/apipie_dsl/apipie_dsls/custom_help.html.erb +10 -0
- data/app/views/apipie_dsl/apipie_dsls/getting_started.html.erb +4 -0
- data/app/views/apipie_dsl/apipie_dsls/index.html.erb +72 -0
- data/app/views/apipie_dsl/apipie_dsls/method.html.erb +52 -0
- data/app/views/apipie_dsl/apipie_dsls/plain.html.erb +116 -0
- data/app/views/apipie_dsl/apipie_dsls/static.html.erb +158 -0
- data/app/views/layouts/apipie_dsl/apipie_dsl.html.erb +26 -0
- data/lib/apipie-dsl.rb +3 -0
- data/lib/apipie_dsl.rb +28 -0
- data/lib/apipie_dsl/Rakefile +6 -0
- data/lib/apipie_dsl/apipie_dsl_module.rb +51 -0
- data/lib/apipie_dsl/application.rb +321 -0
- data/lib/apipie_dsl/class_description.rb +107 -0
- data/lib/apipie_dsl/configuration.rb +87 -0
- data/lib/apipie_dsl/dsl.rb +596 -0
- data/lib/apipie_dsl/errors.rb +68 -0
- data/lib/apipie_dsl/exception_description.rb +39 -0
- data/lib/apipie_dsl/markup.rb +41 -0
- data/lib/apipie_dsl/method_description.rb +112 -0
- data/lib/apipie_dsl/parameter_description.rb +152 -0
- data/lib/apipie_dsl/railtie.rb +15 -0
- data/lib/apipie_dsl/return_description.rb +71 -0
- data/lib/apipie_dsl/routing.rb +17 -0
- data/lib/apipie_dsl/see_description.rb +35 -0
- data/lib/apipie_dsl/static_dispatcher.rb +70 -0
- data/lib/apipie_dsl/tag_list_description.rb +11 -0
- data/lib/apipie_dsl/tasks/apipie_dsl/cache.rake +43 -0
- data/lib/apipie_dsl/tasks/apipie_dsl/static.rake +43 -0
- data/lib/apipie_dsl/tasks/apipie_dsl/static_json.rake +29 -0
- data/lib/apipie_dsl/tasks_utils.rb +137 -0
- data/lib/apipie_dsl/utils.rb +83 -0
- data/lib/apipie_dsl/validator.rb +479 -0
- data/lib/apipie_dsl/version.rb +5 -0
- data/lib/generators/apipie_dsl/install/install_generator.rb +21 -0
- data/lib/generators/apipie_dsl/install/templates/initializer.rb.erb +9 -0
- data/lib/generators/apipie_dsl/views_generator.rb +14 -0
- data/test/test_helper.rb +6 -0
- metadata +220 -0
checksums.yaml
ADDED
@@ -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.
|
data/README.md
ADDED
@@ -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.
|