brainstem 1.4.1 → 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 +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
|