brainstem 1.4.1 → 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +77 -0
- data/README.md +119 -0
- data/docs/api_doc_generator.markdown +45 -4
- data/docs/brainstem_executable.markdown +1 -1
- data/docs/oas_2_docgen.png +0 -0
- data/docs/oas_2_docgen_ascii.txt +78 -0
- data/lib/brainstem/api_docs.rb +23 -9
- data/lib/brainstem/api_docs/abstract_collection.rb +0 -13
- data/lib/brainstem/api_docs/atlas.rb +0 -14
- data/lib/brainstem/api_docs/builder.rb +0 -14
- data/lib/brainstem/api_docs/controller.rb +7 -16
- data/lib/brainstem/api_docs/controller_collection.rb +0 -3
- data/lib/brainstem/api_docs/endpoint.rb +73 -19
- data/lib/brainstem/api_docs/endpoint_collection.rb +0 -7
- data/lib/brainstem/api_docs/formatters/abstract_formatter.rb +0 -2
- data/lib/brainstem/api_docs/formatters/markdown/controller_formatter.rb +1 -9
- data/lib/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter.rb +1 -9
- data/lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb +39 -24
- data/lib/brainstem/api_docs/formatters/markdown/helper.rb +0 -13
- data/lib/brainstem/api_docs/formatters/markdown/presenter_formatter.rb +22 -35
- data/lib/brainstem/api_docs/formatters/open_api_specification/helper.rb +66 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/controller_formatter.rb +57 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/param_definitions_formatter.rb +311 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/response_definitions_formatter.rb +197 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint_collection_formatter.rb +60 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint_formatter.rb +162 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/info_formatter.rb +126 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/presenter_formatter.rb +132 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/security_definitions_formatter.rb +99 -0
- data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/tags_formatter.rb +123 -0
- data/lib/brainstem/api_docs/introspectors/abstract_introspector.rb +0 -7
- data/lib/brainstem/api_docs/introspectors/rails_introspector.rb +1 -20
- data/lib/brainstem/api_docs/presenter.rb +21 -27
- data/lib/brainstem/api_docs/presenter_collection.rb +1 -11
- data/lib/brainstem/api_docs/resolver.rb +1 -8
- data/lib/brainstem/api_docs/sinks/abstract_sink.rb +0 -4
- data/lib/brainstem/api_docs/sinks/controller_presenter_multifile_sink.rb +0 -9
- data/lib/brainstem/api_docs/sinks/open_api_specification_sink.rb +234 -0
- data/lib/brainstem/api_docs/sinks/stdout_sink.rb +0 -5
- data/lib/brainstem/cli.rb +0 -13
- data/lib/brainstem/cli/abstract_command.rb +0 -7
- data/lib/brainstem/cli/generate_api_docs_command.rb +48 -24
- data/lib/brainstem/concerns/controller_dsl.rb +288 -145
- data/lib/brainstem/concerns/formattable.rb +0 -5
- data/lib/brainstem/concerns/optional.rb +0 -1
- data/lib/brainstem/concerns/presenter_dsl.rb +2 -21
- data/lib/brainstem/dsl/configuration.rb +0 -11
- data/lib/brainstem/presenter.rb +0 -4
- data/lib/brainstem/version.rb +1 -1
- data/spec/brainstem/api_docs/abstract_collection_spec.rb +0 -11
- data/spec/brainstem/api_docs/atlas_spec.rb +0 -6
- data/spec/brainstem/api_docs/builder_spec.rb +0 -4
- data/spec/brainstem/api_docs/controller_collection_spec.rb +0 -2
- data/spec/brainstem/api_docs/controller_spec.rb +29 -18
- data/spec/brainstem/api_docs/endpoint_collection_spec.rb +0 -6
- data/spec/brainstem/api_docs/endpoint_spec.rb +343 -13
- data/spec/brainstem/api_docs/formatters/abstract_formatter_spec.rb +0 -2
- data/spec/brainstem/api_docs/formatters/markdown/controller_formatter_spec.rb +0 -1
- data/spec/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter_spec.rb +0 -5
- data/spec/brainstem/api_docs/formatters/markdown/endpoint_formatter_spec.rb +94 -8
- data/spec/brainstem/api_docs/formatters/markdown/helper_spec.rb +0 -8
- data/spec/brainstem/api_docs/formatters/markdown/presenter_formatter_spec.rb +0 -7
- data/spec/brainstem/api_docs/formatters/open_api_specification/helper_spec.rb +210 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/controller_formatter_spec.rb +81 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/param_definitions_formatter_spec.rb +672 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/response_definitions_formatter_spec.rb +335 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint_collection_formatter_spec.rb +59 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint_formatter_spec.rb +308 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/info_formatter_spec.rb +89 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/presenter_formatter_spec.rb +430 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/security_definitions_formatter_spec.rb +190 -0
- data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/tags_formatter_spec.rb +217 -0
- data/spec/brainstem/api_docs/introspectors/abstract_introspector_spec.rb +0 -2
- data/spec/brainstem/api_docs/introspectors/rails_introspector_spec.rb +0 -2
- data/spec/brainstem/api_docs/presenter_collection_spec.rb +0 -2
- data/spec/brainstem/api_docs/presenter_spec.rb +58 -18
- data/spec/brainstem/api_docs/resolver_spec.rb +0 -1
- data/spec/brainstem/api_docs/sinks/controller_presenter_multifile_sink_spec.rb +0 -2
- data/spec/brainstem/api_docs/sinks/open_api_specification_sink_spec.rb +371 -0
- data/spec/brainstem/api_docs_spec.rb +2 -0
- data/spec/brainstem/cli/abstract_command_spec.rb +0 -4
- data/spec/brainstem/cli/generate_api_docs_command_spec.rb +53 -2
- data/spec/brainstem/concerns/controller_dsl_spec.rb +430 -64
- data/spec/brainstem/concerns/presenter_dsl_spec.rb +0 -20
- data/spec/brainstem/preloader_spec.rb +0 -7
- data/spec/brainstem/presenter_spec.rb +0 -1
- data/spec/dummy/rails.rb +0 -1
- data/spec/spec_helpers/db.rb +0 -1
- metadata +37 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9abf1184c78ea43d4e00ae5aa6f2a11fdb663013
|
|
4
|
+
data.tar.gz: 421ffc9a7dd8cce73ad64bcadd40a4108b79c7bf
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8a230a3bbe9bee9643bc96a6b894a8e86669483b1057cb6d7131a3c0ed34817b81739bb1cdc8bc15e64d6c3ca50a84a947133cb68bf3ebbdea702769f5542f59
|
|
7
|
+
data.tar.gz: 0b20e2fc89ce9d3b5ac655b959ca56779d37fc2c22ed2e229666d65925932a46fae573e1ef56b7c15ead24c5fe1d8b8e4109523b531d2c273ee9eecc45549e81
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,82 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
+ **2.0.0** - _05/17/2018_
|
|
4
|
+
- Introduce the capability to document custom response on endpoints
|
|
5
|
+
```ruby
|
|
6
|
+
class ContactsController < ApiController
|
|
7
|
+
brainstem_params do
|
|
8
|
+
actions :index do
|
|
9
|
+
response :hash do
|
|
10
|
+
field :count, :integer,
|
|
11
|
+
info: "Total count of contacts"
|
|
12
|
+
|
|
13
|
+
fields :contacts, :array,
|
|
14
|
+
item_type: :hash,
|
|
15
|
+
info: "Array of contact details" do
|
|
16
|
+
|
|
17
|
+
field :full_name, :string,
|
|
18
|
+
info: "Full name of the contact"
|
|
19
|
+
end
|
|
20
|
+
end
|
|
21
|
+
end
|
|
22
|
+
end
|
|
23
|
+
```
|
|
24
|
+
- Add DSL on controllers to set Open API Specification 2.0 configurations
|
|
25
|
+
```ruby
|
|
26
|
+
class PetsController < ApiController
|
|
27
|
+
brainstem_params do
|
|
28
|
+
# The `tag` configuration allows grouping of all endpoints
|
|
29
|
+
# in a controller under the same group.
|
|
30
|
+
tag "Adopt a Pet"
|
|
31
|
+
|
|
32
|
+
# The `tag_group` configuration introduces another level of nesting
|
|
33
|
+
# and allows grouping multiple controllers under a specific group
|
|
34
|
+
tag_groups "Dogs", "Cats"
|
|
35
|
+
|
|
36
|
+
# A list of default MIME types, endpoints on this controller can consume.
|
|
37
|
+
consumes "application/xml", "application/json"
|
|
38
|
+
|
|
39
|
+
# A list of default MIME types, endpoints on this controller can produce.
|
|
40
|
+
produces "application/xml"
|
|
41
|
+
|
|
42
|
+
# A declaration of which security schemes are applied to endpoints on this controller.
|
|
43
|
+
security []
|
|
44
|
+
|
|
45
|
+
# The default transfer protocols for endpoints on this controller.
|
|
46
|
+
schemes "https", "http"
|
|
47
|
+
|
|
48
|
+
# Additional external documentation
|
|
49
|
+
external_doc description: 'External Doc',
|
|
50
|
+
url: 'www.google.com'
|
|
51
|
+
|
|
52
|
+
# Declares endpoints on this controller to be deprecated.
|
|
53
|
+
deprecated true
|
|
54
|
+
|
|
55
|
+
actions :update do
|
|
56
|
+
# Overriden MIME types the endpoints can consume.
|
|
57
|
+
consumes "application/json"
|
|
58
|
+
|
|
59
|
+
# A list of default MIME types the endpoints can produce.
|
|
60
|
+
produces "application/json"
|
|
61
|
+
|
|
62
|
+
# Security schemes for this endpoint.
|
|
63
|
+
security { "petstore_auth" => [ "write:pets" ] }
|
|
64
|
+
|
|
65
|
+
# Transfer protocols applicable to this endpoint.
|
|
66
|
+
schemes "https"
|
|
67
|
+
|
|
68
|
+
# External documentation for the endpoint.
|
|
69
|
+
external_doc description: 'Stock Market News',
|
|
70
|
+
url: 'www.google.com/finance'
|
|
71
|
+
|
|
72
|
+
# Overrides the deprecated value set on the root context.
|
|
73
|
+
deprecated false
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
```
|
|
78
|
+
- Add the capability to generate Open API Specification 2.0
|
|
79
|
+
|
|
3
80
|
+ **1.4.1** - _05/09/2018_
|
|
4
81
|
- Add the capability to specify an alternate base application / engine the routes are derived from.
|
|
5
82
|
This capability is specific to documemtation generation.
|
data/README.md
CHANGED
|
@@ -364,6 +364,11 @@ bundle exec brainstem generate --help
|
|
|
364
364
|
|
|
365
365
|
## API Documentation
|
|
366
366
|
|
|
367
|
+
Currently, Brainstem supports generation of documentation in the following formats:
|
|
368
|
+
|
|
369
|
+
- Markdown
|
|
370
|
+
- [Open API Specification 2.0 (OAS 2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
|
|
371
|
+
|
|
367
372
|
### The `generate` command
|
|
368
373
|
|
|
369
374
|
Running `bundle exec brainstem generate [ARGS]` will generate the documentation
|
|
@@ -707,6 +712,120 @@ class BlogPostsController < ApiController
|
|
|
707
712
|
end
|
|
708
713
|
```
|
|
709
714
|
|
|
715
|
+
##### `response`
|
|
716
|
+
|
|
717
|
+
Allows documenting custom responses on endpoints. These are only applicable to action contexts.
|
|
718
|
+
|
|
719
|
+
```ruby
|
|
720
|
+
class ContactsController < ApiController
|
|
721
|
+
brainstem_params do
|
|
722
|
+
actions :index do
|
|
723
|
+
response :hash do
|
|
724
|
+
field :count, :integer,
|
|
725
|
+
info: "Total count of contacts"
|
|
726
|
+
|
|
727
|
+
fields :contacts, :array,
|
|
728
|
+
item_type: :hash,
|
|
729
|
+
info: "Array of contact details" do
|
|
730
|
+
|
|
731
|
+
field :full_name, :string,
|
|
732
|
+
info: "Full name of the contact"
|
|
733
|
+
|
|
734
|
+
field :email_address, :string,
|
|
735
|
+
info: "Email address of the contact"
|
|
736
|
+
end
|
|
737
|
+
end
|
|
738
|
+
end
|
|
739
|
+
end
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
##### Specific to Open API Specification 2.0 generation
|
|
743
|
+
|
|
744
|
+
###### `tag` / `tag_groups`
|
|
745
|
+
|
|
746
|
+
These are applicable only to the root context.
|
|
747
|
+
|
|
748
|
+
```ruby
|
|
749
|
+
brainstem_params do
|
|
750
|
+
|
|
751
|
+
# The `tag` configuration allows grouping of all endpoints
|
|
752
|
+
# in a controller under the same group
|
|
753
|
+
tag "Adopt a Pet"
|
|
754
|
+
|
|
755
|
+
# The `tag_group` configuration introduces another level of nesting
|
|
756
|
+
# and allows grouping multiple controllers under a specific group
|
|
757
|
+
tag_groups "Dogs", "Cats"
|
|
758
|
+
end
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
###### `consumes` / `produces` / `security` / `external_doc` / `schemes` / `deprecated`
|
|
762
|
+
|
|
763
|
+
Any of these can be used inside an action context.
|
|
764
|
+
|
|
765
|
+
```ruby
|
|
766
|
+
class PetsController < ApiController
|
|
767
|
+
brainstem_params do
|
|
768
|
+
|
|
769
|
+
# A list of default MIME types, endpoints on this controller can consume.
|
|
770
|
+
consumes "application/xml", "application/json"
|
|
771
|
+
|
|
772
|
+
# A list of default MIME types, endpoints on this controller can produce.
|
|
773
|
+
produces "application/xml"
|
|
774
|
+
|
|
775
|
+
# A declaration of which security schemes are applied to endpoints on this controller.
|
|
776
|
+
security []
|
|
777
|
+
|
|
778
|
+
# The default transfer protocols for endpoints on this controller.
|
|
779
|
+
schemes "https", "http"
|
|
780
|
+
|
|
781
|
+
# Additional external documentation
|
|
782
|
+
external_doc description: 'External Doc',
|
|
783
|
+
url: 'www.google.com'
|
|
784
|
+
|
|
785
|
+
# Declares endpoints on this controller to be deprecated.
|
|
786
|
+
deprecated true
|
|
787
|
+
|
|
788
|
+
actions :update do
|
|
789
|
+
|
|
790
|
+
# Overriden MIME types the endpoints can consume.
|
|
791
|
+
consumes "application/json"
|
|
792
|
+
|
|
793
|
+
# A list of default MIME types the endpoints can produce.
|
|
794
|
+
produces "application/json"
|
|
795
|
+
|
|
796
|
+
# Security schemes for this endpoint.
|
|
797
|
+
security { "petstore_auth" => [ "write:pets" ] }
|
|
798
|
+
|
|
799
|
+
# Transfer protocols applicable to this endpoint.
|
|
800
|
+
schemes "https"
|
|
801
|
+
|
|
802
|
+
# External documentation for the endpoint.
|
|
803
|
+
external_doc description: 'Stock Market News',
|
|
804
|
+
url: 'www.google.com/finance'
|
|
805
|
+
|
|
806
|
+
# Overrides the deprecated value set on the root context.
|
|
807
|
+
deprecated false
|
|
808
|
+
end
|
|
809
|
+
end
|
|
810
|
+
end
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
###### `operation_id`
|
|
814
|
+
|
|
815
|
+
The `operation_id` configuration can only be used within an action context.
|
|
816
|
+
|
|
817
|
+
```ruby
|
|
818
|
+
class BlogPostsController < ApiController
|
|
819
|
+
brainstem_params do
|
|
820
|
+
actions :show do
|
|
821
|
+
|
|
822
|
+
# Unique string used to identify the operation.
|
|
823
|
+
operation_id "getBlogByID"
|
|
824
|
+
end
|
|
825
|
+
end
|
|
826
|
+
end
|
|
827
|
+
```
|
|
828
|
+
|
|
710
829
|
### Extending and Customizing the API Documentation
|
|
711
830
|
|
|
712
831
|
For more information on extending and customizing the API documentation, please
|
|
@@ -124,9 +124,6 @@ Brainstem::ApiDocs.my_config_option
|
|
|
124
124
|
|
|
125
125
|
### Detailed Overview
|
|
126
126
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
127
|
1. `Brainstem::CLI::GenerateApiDocsCommand` instantiates a builder and a sink,
|
|
131
128
|
and hands the output of the builder to the sink, which serializes and stores
|
|
132
129
|
the input somewhere. It also merges the options given to it on the command
|
|
@@ -153,6 +150,11 @@ intelligent interfaces on these collections by which to mutate them. It wraps:
|
|
|
153
150
|
a `Brainstem::ApiDocs::ControllerCollection`;
|
|
154
151
|
- Presenters into `Brainstem::ApiDocs::Presenter` objects, and these into a
|
|
155
152
|
`Brainstem::ApiDocs::PresenterCollection`.
|
|
153
|
+
|
|
154
|
+
#### Specific to Markdown Generation
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
|
|
156
158
|
5. Each of these collection and entity objects includes
|
|
157
159
|
`Brainstem::Concerns::Formattable`, which enables them to be formatted by
|
|
158
160
|
passing them `formatted_as(format, options)`. Formatters inherit from
|
|
@@ -170,6 +172,45 @@ intelligent interfaces on these collections by which to mutate them. It wraps:
|
|
|
170
172
|
controller and presenter as its own file, rather than as a concatenated
|
|
171
173
|
collection.
|
|
172
174
|
6. This sink, having received an instance of the `Atlas`, is responsible for
|
|
173
|
-
serializing—primarily invoking formatting—and then outputting
|
|
175
|
+
serializing — primarily invoking formatting — and then outputting
|
|
176
|
+
the result somewhere, whether to `$stdout`, a file or files on disk, or a
|
|
177
|
+
remote location.
|
|
178
|
+
|
|
179
|
+
### Specific to Open API Specification generation
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
5. Each of these collection and entity objects includes
|
|
184
|
+
`Brainstem::Concerns::Formattable`, which enables them to be formatted by
|
|
185
|
+
passing them `formatted_as(format, options)`. Formatters inherit from
|
|
186
|
+
`Brainstem::ApiDocs::Formatters::AbstractFormatter`, are loaded by
|
|
187
|
+
`Cerebellum::ApiDocs`, and are stored by self-assigned type. Some or all of
|
|
188
|
+
these formatters may be provided for this type, depending on the desired
|
|
189
|
+
behaviour.
|
|
190
|
+
|
|
191
|
+
Brainstem includes an implementation of an `Open API Specification` formatter,
|
|
192
|
+
stored under the type `:oas_v2`. The formatters are listed below:
|
|
193
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::PresenterFormatter`
|
|
194
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::ControllerFormatter`
|
|
195
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointCollectionFormatter`
|
|
196
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointFormatter`
|
|
197
|
+
|
|
198
|
+
The EndpointFormatter uses the following formatters:
|
|
199
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ParamDefinitionsFormatter`
|
|
200
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ResponseDefinitionsFormatter`
|
|
201
|
+
|
|
202
|
+
The Open API Specification Sink also uses some formatters to add metadata to the specification. They
|
|
203
|
+
are listed below:
|
|
204
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::InfoFormatter`
|
|
205
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::SecurityDefinitionsFormatter`
|
|
206
|
+
- `Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::TagsFormatter`
|
|
207
|
+
|
|
208
|
+
Note that there is not a `ControllerCollectionFormatter`, nor a
|
|
209
|
+
`PresenterCollectionFormatter` included: this is because the Sink shares
|
|
210
|
+
partial responsibility for collection formatting, and in the case of the
|
|
211
|
+
`Brainstem::ApiDocs::Sinks::OpenApiSpecificationSink`, outputs all
|
|
212
|
+
controllers and presenters into a single `specification.yml` file.
|
|
213
|
+
6. This sink, having received an instance of the `Atlas`, is responsible for
|
|
214
|
+
serializing — primarily invoking formatting — and then outputting
|
|
174
215
|
the result somewhere, whether to `$stdout`, a file or files on disk, or a
|
|
175
216
|
remote location.
|
|
Binary file
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
Load the following rows into asciiflow.com to edit:
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
+----------------------------------------+ +-----------------------------+ +---------------------------------------------------------+
|
|
5
|
+
| Brainstem::CLI::GenerateApiDocsCommand +------+-----> Brainstem::ApiDocs::Builder +-------+----> Brainstem::ApiDocs::Introspectors::AbstractIntrospector <-----+
|
|
6
|
+
+----------------------------------------+ | +-----------------------------+ | +---------------------------------------------------------+ | U
|
|
7
|
+
| | | | S
|
|
8
|
+
| | | +------------------------------------------------------+ | E
|
|
9
|
+
| | +----> Brainstem::ApiDocs::Introspectors::RailsIntrospector <---+ S
|
|
10
|
+
| | +------------------------------------------------------+ |
|
|
11
|
+
| | |
|
|
12
|
+
| | +------------------------------------+
|
|
13
|
+
| | |
|
|
14
|
+
| | +--------------------------++ +----------------------------------------+
|
|
15
|
+
| +----> Brainstem::ApiDocs::Atlas +------------> Brainstem::ApiDocs::AbstractCollection |
|
|
16
|
+
| | +------------------------^--+ +----------------------------------------+ +-----------------------------------------------+
|
|
17
|
+
| | | | | |
|
|
18
|
+
| | | | +-------------------------------------------+ | +--------------------------------+ |
|
|
19
|
+
| | | +----> Brainstem::ApiDocs::EndpointCollection | ----+----> Brainstem::ApiDocs::Endpoint +------------+
|
|
20
|
+
| | | | +-------------------------------------------+ +--------------------------------+ | |
|
|
21
|
+
| | | | | |
|
|
22
|
+
| | | | +-------------------------------------------+ +--------------------------------+ | |
|
|
23
|
+
| | | +----> Brainstem::ApiDocs::ControllerCollection | ---------> Brainstem::ApiDocs::Controller +------+ | |
|
|
24
|
+
| | | | +-------------------------------------------+ +--------------------------------+ | | |
|
|
25
|
+
| | | | | | |
|
|
26
|
+
| | | | +-------------------------------------------+ +--------------------------------+ | | |
|
|
27
|
+
| | | +----> Brainstem::ApiDocs::PresenterCollection | ---------> Brainstem::ApiDocs::Presenter +---+ | | |
|
|
28
|
+
| | | +-------------------------------------------+ +--------------------------------+ | | | |
|
|
29
|
+
| | | | | | |
|
|
30
|
+
| | +-------------------------------------------+ | | | |
|
|
31
|
+
| | | U | | | |
|
|
32
|
+
| | +-----------------------------------------+ | S | | | |
|
|
33
|
+
| +----> Brainstem::ApiDocs::Sinks::AbstractSink +--------------------------> E | | | |
|
|
34
|
+
| +-----------------------------------------+ | S | | | |
|
|
35
|
+
| | | | | | |
|
|
36
|
+
| | +-------------------------------------------------------------+ | | | | |
|
|
37
|
+
| +----> Brainstem::ApiDocs::Sinks::OpenApiSpecificationSink +-+ | | | | U
|
|
38
|
+
| +-------------------------------------------------------------+ | | | | S
|
|
39
|
+
| | | | | E
|
|
40
|
+
| +--------------------+ +---------------------------------------------------+ | | | | S
|
|
41
|
+
+-----> Brainstem::ApiDocs +---------------------> Brainstem::ApiDocs::Formatters::AbstractFormatter | | | | |
|
|
42
|
+
+--------------------+ +---------------------------------------------------+ | | | |
|
|
43
|
+
| | | | |
|
|
44
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
45
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::InfoFormatter | | | | |
|
|
46
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
47
|
+
| | | | |
|
|
48
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
49
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::SecurityDefinitionsFormatter| | | | |
|
|
50
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
51
|
+
| | | | |
|
|
52
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
53
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::TagsFormatter | | | | |
|
|
54
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
55
|
+
| | | | |
|
|
56
|
+
| +---------------------------------------------------------------------------------------------+ | | | |
|
|
57
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::PresenterFormatter <--------------------------------------+ | | |
|
|
58
|
+
| +---------------------------------------------------------------------------------------------+ | | |
|
|
59
|
+
| | | |
|
|
60
|
+
| +---------------------------------------------------------------------------------------------+ | | |
|
|
61
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::ControllerFormatter <-----------------------------------------+ | |
|
|
62
|
+
| +---------------------------------------------------------------------------------------------+ | |
|
|
63
|
+
| | |
|
|
64
|
+
| +---------------------------------------------------------------------------------------------+ | |
|
|
65
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointCollectionFormatter <--------------------------------------------+ |
|
|
66
|
+
| +---------------------------------------------------------------------------------------------+ |
|
|
67
|
+
| |
|
|
68
|
+
| +---------------------------------------------------------------------------------------------+ |
|
|
69
|
+
+----> Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointFormatter <-----------------------------------------------+
|
|
70
|
+
+---------------------------------------------------------------------------------------+--+--+
|
|
71
|
+
| |
|
|
72
|
+
+------------------------------------------------------------------------------------------------------------------------------------------+ | | U
|
|
73
|
+
| Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ParamDefinitionsFormatter <---+ | S
|
|
74
|
+
+------------------------------------------------------------------------------------------------------------------------------------------+ | E
|
|
75
|
+
| S
|
|
76
|
+
+------------------------------------------------------------------------------------------------------------------------------------------+ |
|
|
77
|
+
| Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ResponseDefinitionsFormatter <------+
|
|
78
|
+
+------------------------------------------------------------------------------------------------------------------------------------------+
|
data/lib/brainstem/api_docs.rb
CHANGED
|
@@ -8,6 +8,19 @@ module Brainstem
|
|
|
8
8
|
File.expand_path("./brainstem_docs")
|
|
9
9
|
end
|
|
10
10
|
|
|
11
|
+
#
|
|
12
|
+
# Defines the naming pattern of the Open API Specification file.
|
|
13
|
+
#
|
|
14
|
+
# The following tokens will be substituted:
|
|
15
|
+
#
|
|
16
|
+
# - {{version}} : the specified version
|
|
17
|
+
# - {{extension} : the specified file extension
|
|
18
|
+
#
|
|
19
|
+
# @see #output_extension
|
|
20
|
+
#
|
|
21
|
+
config_accessor(:oas_filename_pattern) do
|
|
22
|
+
File.join("endpoints", "{{version}}.{{extension}}")
|
|
23
|
+
end
|
|
11
24
|
|
|
12
25
|
#
|
|
13
26
|
# Defines the naming pattern of each controller documentation file.
|
|
@@ -26,7 +39,6 @@ module Brainstem
|
|
|
26
39
|
File.join("endpoints", "{{name}}.{{extension}}")
|
|
27
40
|
end
|
|
28
41
|
|
|
29
|
-
|
|
30
42
|
#
|
|
31
43
|
# Defines the naming pattern of each presenter documentation file.
|
|
32
44
|
#
|
|
@@ -41,7 +53,6 @@ module Brainstem
|
|
|
41
53
|
File.join("objects", "{{name}}.{{extension}}")
|
|
42
54
|
end
|
|
43
55
|
|
|
44
|
-
|
|
45
56
|
#
|
|
46
57
|
# Defines the naming pattern for the relative link to each controller documentation file.
|
|
47
58
|
#
|
|
@@ -56,7 +67,6 @@ module Brainstem
|
|
|
56
67
|
controller_filename_pattern
|
|
57
68
|
end
|
|
58
69
|
|
|
59
|
-
|
|
60
70
|
#
|
|
61
71
|
# Defines the naming pattern for the relative link to each presenter documentation file.
|
|
62
72
|
#
|
|
@@ -71,6 +81,10 @@ module Brainstem
|
|
|
71
81
|
presenter_filename_pattern
|
|
72
82
|
end
|
|
73
83
|
|
|
84
|
+
#
|
|
85
|
+
# Defines the base path for the given API.
|
|
86
|
+
#
|
|
87
|
+
config_accessor(:base_path) { "/v2" }
|
|
74
88
|
|
|
75
89
|
#
|
|
76
90
|
# Defines the extension that should be used for output files.
|
|
@@ -79,7 +93,6 @@ module Brainstem
|
|
|
79
93
|
#
|
|
80
94
|
config_accessor(:output_extension) { "markdown" }
|
|
81
95
|
|
|
82
|
-
|
|
83
96
|
#
|
|
84
97
|
# Defines the class that all presenters should inherit from / be drawn
|
|
85
98
|
# from.
|
|
@@ -93,7 +106,6 @@ module Brainstem
|
|
|
93
106
|
"::Brainstem::Presenter"
|
|
94
107
|
end
|
|
95
108
|
|
|
96
|
-
|
|
97
109
|
#
|
|
98
110
|
# Defines the class that all controllers should inherit from / be drawn
|
|
99
111
|
# from.
|
|
@@ -114,22 +126,18 @@ module Brainstem
|
|
|
114
126
|
#
|
|
115
127
|
config_accessor(:base_application_class) { nil }
|
|
116
128
|
|
|
117
|
-
|
|
118
129
|
#
|
|
119
130
|
# If associations on a presenter have no description, i.e. no documentation,
|
|
120
131
|
# should they be documented anyway?
|
|
121
132
|
#
|
|
122
133
|
config_accessor(:document_empty_presenter_associations) { true }
|
|
123
134
|
|
|
124
|
-
|
|
125
135
|
#
|
|
126
136
|
# If filters on a presenter have no `:info` key, i.e. no documentation,
|
|
127
137
|
# should they be documented anyway?
|
|
128
138
|
#
|
|
129
139
|
config_accessor(:document_empty_presenter_filters) { true }
|
|
130
140
|
|
|
131
|
-
|
|
132
|
-
|
|
133
141
|
FORMATTERS = {
|
|
134
142
|
|
|
135
143
|
# Formatter for entire response
|
|
@@ -145,6 +153,12 @@ module Brainstem
|
|
|
145
153
|
endpoint: {},
|
|
146
154
|
presenter: {},
|
|
147
155
|
|
|
156
|
+
# Formatter for Open API Specifications
|
|
157
|
+
info: {},
|
|
158
|
+
response: {},
|
|
159
|
+
parameters: {},
|
|
160
|
+
security: {},
|
|
161
|
+
tags: {},
|
|
148
162
|
}
|
|
149
163
|
end
|
|
150
164
|
end
|