grape-apidoc 0.0.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: '00539705ff2d9e78efbb1f426ebfd137b8341b899f30ab6b4f043de5491ab200'
4
+ data.tar.gz: 3c581b505833b9a5a0a22243512e1e4a2eb8e97ec6eb612eb18f7f1b6b42c0cb
5
+ SHA512:
6
+ metadata.gz: d01f82031b6b9eeafda3138012aea74b81ffe7b679161905e1c6d9acca59d608783d6e3da1cd4ff116ef04f8c58ac1ac106bc97eb28b2bbe8fa392d725fff6a1
7
+ data.tar.gz: 31a64d4676dbd91be7783b1a9dd435c96ba95523e7980a36d38d8e7d7e827153c9890b6c520e15707d714f2b7101225a6b1bfadf8efcddfa505be5254937d36a
@@ -0,0 +1,21 @@
1
+ name: Test
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ ruby-version: ["2.7", "3.0", "3.1", "3.2"]
15
+ steps:
16
+ - uses: actions/checkout@v3
17
+ - uses: ruby/setup-ruby@v1
18
+ with:
19
+ ruby-version: ${{ matrix.ruby-version }}
20
+ bundler-cache: true
21
+ - run: bundle exec rake
data/.gitignore ADDED
@@ -0,0 +1 @@
1
+ .ruby-version
data/.rubocop.yml ADDED
@@ -0,0 +1,10 @@
1
+ inherit_gem:
2
+ rubocop-bsm:
3
+ - default.yml
4
+ inherit_mode:
5
+ merge:
6
+ - Exclude
7
+
8
+ Naming/FileName:
9
+ Exclude:
10
+ - lib/grape-apidoc.rb
data/Gemfile ADDED
@@ -0,0 +1,7 @@
1
+ source 'http://rubygems.org'
2
+ gemspec
3
+ gem 'grape-entity'
4
+ gem 'mustermann', '>= 3'
5
+ gem 'rake'
6
+ gem 'rspec'
7
+ gem 'rubocop-bsm'
data/Gemfile.lock ADDED
@@ -0,0 +1,122 @@
1
+ PATH
2
+ remote: .
3
+ specs:
4
+ grape-apidoc (0.0.2)
5
+ grape
6
+
7
+ GEM
8
+ remote: http://rubygems.org/
9
+ specs:
10
+ activesupport (7.0.4.2)
11
+ concurrent-ruby (~> 1.0, >= 1.0.2)
12
+ i18n (>= 1.6, < 2)
13
+ minitest (>= 5.1)
14
+ tzinfo (~> 2.0)
15
+ ast (2.4.2)
16
+ builder (3.2.4)
17
+ concurrent-ruby (1.2.0)
18
+ diff-lcs (1.5.0)
19
+ dry-core (1.0.0)
20
+ concurrent-ruby (~> 1.0)
21
+ zeitwerk (~> 2.6)
22
+ dry-inflector (1.0.0)
23
+ dry-logic (1.5.0)
24
+ concurrent-ruby (~> 1.0)
25
+ dry-core (~> 1.0, < 2)
26
+ zeitwerk (~> 2.6)
27
+ dry-types (1.7.0)
28
+ concurrent-ruby (~> 1.0)
29
+ dry-core (~> 1.0, < 2)
30
+ dry-inflector (~> 1.0, < 2)
31
+ dry-logic (>= 1.4, < 2)
32
+ zeitwerk (~> 2.6)
33
+ grape (1.7.0)
34
+ activesupport
35
+ builder
36
+ dry-types (>= 1.1)
37
+ mustermann-grape (~> 1.0.0)
38
+ rack (>= 1.3.0)
39
+ rack-accept
40
+ grape-entity (0.10.2)
41
+ activesupport (>= 3.0.0)
42
+ multi_json (>= 1.3.2)
43
+ i18n (1.12.0)
44
+ concurrent-ruby (~> 1.0)
45
+ json (2.6.3)
46
+ minitest (5.17.0)
47
+ multi_json (1.15.0)
48
+ mustermann (3.0.0)
49
+ ruby2_keywords (~> 0.0.1)
50
+ mustermann-grape (1.0.2)
51
+ mustermann (>= 1.0.0)
52
+ parallel (1.22.1)
53
+ parser (3.2.0.0)
54
+ ast (~> 2.4.1)
55
+ rack (3.0.4.1)
56
+ rack-accept (0.4.5)
57
+ rack (>= 0.4)
58
+ rainbow (3.1.1)
59
+ rake (13.0.6)
60
+ regexp_parser (2.6.2)
61
+ rexml (3.2.5)
62
+ rspec (3.12.0)
63
+ rspec-core (~> 3.12.0)
64
+ rspec-expectations (~> 3.12.0)
65
+ rspec-mocks (~> 3.12.0)
66
+ rspec-core (3.12.0)
67
+ rspec-support (~> 3.12.0)
68
+ rspec-expectations (3.12.2)
69
+ diff-lcs (>= 1.2.0, < 2.0)
70
+ rspec-support (~> 3.12.0)
71
+ rspec-mocks (3.12.3)
72
+ diff-lcs (>= 1.2.0, < 2.0)
73
+ rspec-support (~> 3.12.0)
74
+ rspec-support (3.12.0)
75
+ rubocop (1.44.1)
76
+ json (~> 2.3)
77
+ parallel (~> 1.10)
78
+ parser (>= 3.2.0.0)
79
+ rainbow (>= 2.2.2, < 4.0)
80
+ regexp_parser (>= 1.8, < 3.0)
81
+ rexml (>= 3.2.5, < 4.0)
82
+ rubocop-ast (>= 1.24.1, < 2.0)
83
+ ruby-progressbar (~> 1.7)
84
+ unicode-display_width (>= 2.4.0, < 3.0)
85
+ rubocop-ast (1.24.1)
86
+ parser (>= 3.1.1.0)
87
+ rubocop-bsm (0.6.1)
88
+ rubocop (~> 1.0)
89
+ rubocop-performance
90
+ rubocop-rake
91
+ rubocop-rspec
92
+ rubocop-capybara (2.17.0)
93
+ rubocop (~> 1.41)
94
+ rubocop-performance (1.15.2)
95
+ rubocop (>= 1.7.0, < 2.0)
96
+ rubocop-ast (>= 0.4.0)
97
+ rubocop-rake (0.6.0)
98
+ rubocop (~> 1.0)
99
+ rubocop-rspec (2.18.1)
100
+ rubocop (~> 1.33)
101
+ rubocop-capybara (~> 2.17)
102
+ ruby-progressbar (1.11.0)
103
+ ruby2_keywords (0.0.5)
104
+ tzinfo (2.0.6)
105
+ concurrent-ruby (~> 1.0)
106
+ unicode-display_width (2.4.2)
107
+ zeitwerk (2.6.6)
108
+
109
+ PLATFORMS
110
+ x86_64-linux
111
+
112
+ DEPENDENCIES
113
+ bundler
114
+ grape-apidoc!
115
+ grape-entity
116
+ mustermann (>= 3)
117
+ rake
118
+ rspec
119
+ rubocop-bsm
120
+
121
+ BUNDLED WITH
122
+ 2.3.16
data/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2021 Black Square Media Ltd
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
data/README.md ADDED
@@ -0,0 +1,27 @@
1
+ # grape-apidoc [![Test](https://github.com/bsm/grape-apidoc/actions/workflows/test.yml/badge.svg)](https://github.com/bsm/grape-apidoc/actions/workflows/test.yml)
2
+
3
+ [Rake](https://github.com/ruby/rake) task to generate [Markdown](https://en.wikipedia.org/wiki/Markdown) documentation for [Grape](https://github.com/ruby-grape/grape)/[Grape::Entity](https://github.com/ruby-grape/grape-entity)-based APIs
4
+
5
+ ## Getting started
6
+
7
+ ```ruby
8
+ # Gemfile
9
+ group :development do # most common use env is env=development
10
+ gem 'grape-apidoc'
11
+ end
12
+ ```
13
+
14
+ ```ruby
15
+ # Rakefile
16
+ begin
17
+ require 'grape/apidoc'
18
+ Grape::Apidoc::RakeTask.new(:apidoc, root_api_class: Grape::App) # point it to the top-level API class
19
+ rescue LoadError
20
+ nil # so it does not fail in non-development environment
21
+ end
22
+ ```
23
+
24
+ ## Examples
25
+
26
+ - API: [spec/scenario/example.rb](spec/scenario/example.rb)
27
+ - Resulting doc: [spec/fixtures/example.md](spec/fixtures/example.md)
data/Rakefile ADDED
@@ -0,0 +1,9 @@
1
+ require 'bundler/setup'
2
+ require 'bundler/gem_tasks'
3
+ require 'rspec/core/rake_task'
4
+ require 'rubocop/rake_task'
5
+
6
+ RSpec::Core::RakeTask.new(:spec)
7
+ RuboCop::RakeTask.new(:rubocop)
8
+
9
+ task default: %i[rubocop spec]
@@ -0,0 +1,19 @@
1
+ Gem::Specification.new do |s|
2
+ s.name = 'grape-apidoc'
3
+ s.version = '0.0.2'
4
+ s.authors = ['Black Square Media Ltd.']
5
+ s.email = ['info@blacksquaremedia.com']
6
+ s.summary = 'Markdown documentation for Grape APIs'
7
+ s.description = 'github.com/ruby/rake task to generate Markdown documentation for github.com/ruby-grape/grape + github.com/ruby-grape/grape-entity based APIs'
8
+ s.homepage = 'https://github.com/bsm/grape-apidoc'
9
+ s.license = 'Apache-2.0'
10
+
11
+ s.files = `git ls-files -z`.split("\x0").reject {|f| f.start_with?('spec/') }
12
+ s.require_paths = ['lib']
13
+ s.required_ruby_version = '>= 2.7'
14
+
15
+ s.add_dependency 'grape'
16
+
17
+ s.add_development_dependency 'bundler'
18
+ s.metadata['rubygems_mfa_required'] = 'true'
19
+ end
@@ -0,0 +1,11 @@
1
+ class Grape::Apidoc::RakeTask < Rake::TaskLib
2
+ def initialize(name = :apidoc, root_api_class: nil, output: $stdout)
3
+ super()
4
+
5
+ desc 'Generate markdown documentation for API'
6
+ task(name => :environment) do
7
+ doc = Grape::Apidoc.new(root_api_class, output: output)
8
+ doc.write!
9
+ end
10
+ end
11
+ end
@@ -0,0 +1,26 @@
1
+ # column cell widths
2
+ class Grape::Apidoc::TableFormat < Array
3
+ def format(*values)
4
+ str = '|'
5
+
6
+ each_with_index do |width, index|
7
+ str << ' '
8
+ str << (values[index] || '').ljust(width)
9
+ str << ' |'
10
+ end
11
+
12
+ str
13
+ end
14
+
15
+ def separator
16
+ str = '|'
17
+
18
+ each_with_index do |width, _index|
19
+ str << ' '
20
+ str << ('-' * width)
21
+ str << ' |'
22
+ end
23
+
24
+ str
25
+ end
26
+ end
@@ -0,0 +1,188 @@
1
+ module Grape
2
+ class Apidoc
3
+ autoload :RakeTask, 'grape/apidoc/rake_task'
4
+ autoload :TableFormat, 'grape/apidoc/table_format'
5
+
6
+ ENTITY_FIELDS_TABLE = TableFormat.new([20, 10, 30, 10]).freeze # Field, Type, Description, Values
7
+ ROUTE_FIELDS_TABLE = TableFormat.new([20, 10, 40]).freeze # Field, Type, Description
8
+
9
+ def initialize(root_api_class = nil, output: $stdout)
10
+ @api = root_api_class || detect_root_api_class
11
+ @out = output
12
+ end
13
+
14
+ def write!
15
+ write_entities! if defined?(Grape::Entity)
16
+ write_routes!
17
+ end
18
+
19
+ private
20
+
21
+ def detect_root_api_class
22
+ # performance shortcut for https://github.com/bsm/grape-app/
23
+ return Grape::App if defined?(Grape::App)
24
+
25
+ # root api is the one with largest route count:
26
+ Grape::API.descendants.max do |a, b|
27
+ a.try(:routes)&.count <=> b.try(:routes)&.count
28
+ end
29
+ end
30
+
31
+ # Returns all the entities used in app.
32
+ def entities
33
+ @entities ||= begin
34
+ acc = {}
35
+ @api.routes.filter_map(&:entity).each do |entity|
36
+ collect_entities(acc, entity)
37
+ end
38
+ acc.keys.sort_by(&:name)
39
+ end
40
+ end
41
+
42
+ # Recursively collects entities.
43
+ # @param acc Hash entity_class => true lookup/accumulator
44
+ # @param entity Grape::Entity root/seed entity
45
+ def collect_entities(acc, entity)
46
+ return if acc[entity]
47
+
48
+ acc[entity] = true
49
+
50
+ entity.root_exposures.each do |exp|
51
+ via = exp.try(:using_class_name)
52
+ collect_entities(acc, via) if via
53
+ end
54
+ end
55
+
56
+ def write_entities!
57
+ @out.puts '# Entities'
58
+ @out.puts
59
+
60
+ entities.each do |entity|
61
+ write_entity_header!(entity)
62
+ @out.puts
63
+
64
+ write_entity_fields!(entity)
65
+ @out.puts
66
+ end
67
+ end
68
+
69
+ def write_entity_header!(entity)
70
+ @out.puts "## #{entity_name(entity)}"
71
+ end
72
+
73
+ def write_entity_fields!(entity)
74
+ unless entity.root_exposures.present?
75
+ @out.puts '*No fields exposed.*'
76
+ return
77
+ end
78
+
79
+ @out.puts ENTITY_FIELDS_TABLE.format('Field', 'Type', 'Description', 'Values')
80
+ @out.puts ENTITY_FIELDS_TABLE.separator
81
+
82
+ entity.root_exposures.each do |exposure|
83
+ name = exposure.key
84
+ doc = entity.documentation[name] || {}
85
+ type, desc, vals = doc.values_at(:type, :desc, :values)
86
+
87
+ # fall back to `using:...`
88
+ unless type
89
+ via = exposure.try(:using_class_name)
90
+ if via
91
+ via_name = entity_name(via)
92
+ type = "[#{via_name}](##{identifier(via_name)})"
93
+ end
94
+ end
95
+
96
+ type = "[#{type}]" if doc[:is_array]
97
+ @out.puts ENTITY_FIELDS_TABLE.format(name.to_s, type.to_s, desc.to_s, vals&.join(', '))
98
+ end
99
+ end
100
+
101
+ def write_routes!
102
+ @out.puts '# Routes'
103
+ @out.puts
104
+
105
+ @api.routes.each do |route|
106
+ write_route_header!(route)
107
+ @out.puts
108
+
109
+ # list items:
110
+ write_route_retval!(route)
111
+ write_route_security!(route)
112
+ @out.puts
113
+
114
+ write_route_params!(route)
115
+ @out.puts
116
+ end
117
+ end
118
+
119
+ def write_route_header!(route)
120
+ method = route.request_method
121
+ path = route.path
122
+ .sub(':version', route.version.to_s)
123
+ .sub('(.:format)', '')
124
+ @out.puts "## #{method} #{path}"
125
+
126
+ return unless route.description.present?
127
+
128
+ @out.puts
129
+ @out.puts route.description
130
+ end
131
+
132
+ def write_route_security!(route)
133
+ security = route.settings.dig(:description, :security)
134
+ return unless security.present?
135
+
136
+ security_desc = security.map {|k, v| "#{k}=#{v.inspect}" }.join(' ')
137
+
138
+ @out.puts "- **Security**: `#{security_desc}`"
139
+ end
140
+
141
+ def write_route_retval!(route)
142
+ entity = route.try(&:entity)
143
+ return unless entity
144
+
145
+ array_prefix = 'List of ' if route.settings.dig(:description, :is_array)
146
+
147
+ name = entity_name(entity)
148
+ @out.puts "- **Returns**: #{array_prefix}[#{name}](##{identifier(name)})"
149
+ end
150
+
151
+ def write_route_params!(route)
152
+ return unless route.params.present?
153
+
154
+ @out.puts '**Parameters**:'
155
+ @out.puts
156
+
157
+ @out.puts ROUTE_FIELDS_TABLE.format('Parameter', 'Type', 'Description')
158
+ @out.puts ROUTE_FIELDS_TABLE.separator
159
+
160
+ route.params.each do |name, doc|
161
+ # route.params includes path params as well, like `id => ''`
162
+ # (not a hash, like normal params):
163
+ doc = {} unless doc.is_a?(Hash)
164
+
165
+ # Problem: it's pretty much impossible to match Entity to model to dig column types.
166
+ # Problem: it's not guaranteed that Entity exposures match params.
167
+ # Need to either enforce some requirements for organizing API or give up.
168
+ type = doc[:type] || ''
169
+ desc = doc.except(:type).map {|k, v| "#{k}: #{v}" }.join(', ')
170
+ @out.puts ROUTE_FIELDS_TABLE.format(name.to_s, type, desc)
171
+ end
172
+ end
173
+
174
+ def identifier(str)
175
+ # FIXME: this is github-specific. At some point, maybe extract smth like testable Grape::Apidoc::Flavor::Github or so.
176
+
177
+ # "Foo::Bar is a foo_bar, - definitely" -> "foobar-is-a-foo_bar-----definitely"
178
+ str.downcase.gsub(/[^0-9a-z_-]+/, '').gsub('\s', '-')
179
+ end
180
+
181
+ def entity_name(entity)
182
+ entity.name
183
+ .split('::')
184
+ .filter_map {|s| s.delete_suffix('Entity').presence } # Foo::Entity, FooEntity -> just Foo
185
+ .join(':')
186
+ end
187
+ end
188
+ end
@@ -0,0 +1 @@
1
+ require 'grape/apidoc'
metadata ADDED
@@ -0,0 +1,86 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: grape-apidoc
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.2
5
+ platform: ruby
6
+ authors:
7
+ - Black Square Media Ltd.
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2023-02-01 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: grape
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - ">="
18
+ - !ruby/object:Gem::Version
19
+ version: '0'
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - ">="
25
+ - !ruby/object:Gem::Version
26
+ version: '0'
27
+ - !ruby/object:Gem::Dependency
28
+ name: bundler
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: '0'
34
+ type: :development
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - ">="
39
+ - !ruby/object:Gem::Version
40
+ version: '0'
41
+ description: github.com/ruby/rake task to generate Markdown documentation for github.com/ruby-grape/grape
42
+ + github.com/ruby-grape/grape-entity based APIs
43
+ email:
44
+ - info@blacksquaremedia.com
45
+ executables: []
46
+ extensions: []
47
+ extra_rdoc_files: []
48
+ files:
49
+ - ".github/workflows/test.yml"
50
+ - ".gitignore"
51
+ - ".rubocop.yml"
52
+ - Gemfile
53
+ - Gemfile.lock
54
+ - LICENSE
55
+ - README.md
56
+ - Rakefile
57
+ - grape-apidoc.gemspec
58
+ - lib/grape-apidoc.rb
59
+ - lib/grape/apidoc.rb
60
+ - lib/grape/apidoc/rake_task.rb
61
+ - lib/grape/apidoc/table_format.rb
62
+ homepage: https://github.com/bsm/grape-apidoc
63
+ licenses:
64
+ - Apache-2.0
65
+ metadata:
66
+ rubygems_mfa_required: 'true'
67
+ post_install_message:
68
+ rdoc_options: []
69
+ require_paths:
70
+ - lib
71
+ required_ruby_version: !ruby/object:Gem::Requirement
72
+ requirements:
73
+ - - ">="
74
+ - !ruby/object:Gem::Version
75
+ version: '2.7'
76
+ required_rubygems_version: !ruby/object:Gem::Requirement
77
+ requirements:
78
+ - - ">="
79
+ - !ruby/object:Gem::Version
80
+ version: '0'
81
+ requirements: []
82
+ rubygems_version: 3.4.1
83
+ signing_key:
84
+ specification_version: 4
85
+ summary: Markdown documentation for Grape APIs
86
+ test_files: []