r2-oas 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +13 -1
  3. data/Gemfile.lock +85 -70
  4. data/README.ja.md +11 -413
  5. data/README.md +9 -409
  6. data/docs/.nojekyll +0 -0
  7. data/docs/README.md +326 -0
  8. data/docs/_sidebar.md +22 -0
  9. data/docs/index.html +28 -0
  10. data/docs/{versions/v3.md → schema/3.0.0.md} +1 -1
  11. data/docs/setting/COC.md +14 -0
  12. data/docs/setting/CORS.md +22 -0
  13. data/docs/setting/configure.md +163 -0
  14. data/docs/{HOW_TO_ANALYZE_DOCS.md → usage/analyze_docs.md} +8 -8
  15. data/docs/usage/clean_docs.md +19 -0
  16. data/docs/{HOW_TO_DEPLOY_SWAGGER_DOC.md → usage/deploy_docs.md} +8 -8
  17. data/docs/{HOW_TO_DISPLAY_PATHS_LIST.md → usage/display_paths_list.md} +15 -8
  18. data/docs/{HOW_TO_DISPLAY_PATHS_STATS.md → usage/display_paths_stats.md} +15 -14
  19. data/docs/{HOW_TO_START_SWAGGER_EDITOR.md → usage/edit_docs.md} +10 -10
  20. data/docs/{HOW_TO_GENERATE_DOCS.md → usage/generate_docs.md} +9 -9
  21. data/docs/{HOW_TO_MONITOR_SWAGGER_DOC.md → usage/monitor_docs.md} +9 -9
  22. data/docs/usage/use_hook_methods.md +236 -0
  23. data/docs/{HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md → usage/use_hook_to_generate_docs.md} +6 -15
  24. data/docs/{HOW_TO_USE_SCHEMA_NAMESPACE.md → usage/use_schema_namespace.md} +16 -9
  25. data/docs/{HOW_TO_USE_TAG_NAMESPACE.md → usage/use_tag_namespace.md} +22 -16
  26. data/docs/{HOW_TO_START_SWAGGER_UI.md → usage/view_docs.md} +10 -10
  27. data/lib/r2-oas/app_configuration.rb +19 -16
  28. data/lib/r2-oas/deploy/client.rb +1 -1
  29. data/lib/r2-oas/schema/v3/object/path_item_object.rb +17 -9
  30. data/lib/r2-oas/version.rb +1 -1
  31. data/r2-oas.gemspec +5 -19
  32. metadata +42 -46
  33. data/docs/HOW_TO_CLEAN_DOCS.md +0 -19
@@ -1,6 +1,8 @@
1
- ## BasicUsage
1
+ ## Use hook to generate docs
2
2
 
3
- `custom_path_item_object.rb`
3
+ ## Prepare
4
+
5
+ prepare a file like `custom_path_item_object.rb`
4
6
 
5
7
  ```ruby
6
8
  class CustomPathItemObject < R2OAS::Schema::V3::PathItemObject
@@ -56,25 +58,14 @@ end
56
58
  require_relative 'custom_path_item_object'
57
59
 
58
60
  R2OAS.configure do |config|
59
- config.root_dir_path = "./oas_docs"
60
- config.schema_save_dir_name = "src"
61
- config.doc_save_file_name = "oas_doc.yml"
62
- config.force_update_schema = false
63
- config.use_tag_namespace = true
64
- config.use_schema_namespace = false
65
- config.server.data = [
66
- {
67
- url: "http://localhost:3000",
68
- description: "localhost"
69
- }
70
- ]
71
- config.interval_to_save_edited_tmp_schema = 15
72
61
  config.use_object_classes.merge!({
73
62
  path_item_object: CustomPathItemObject
74
63
  })
75
64
  end
76
65
  ```
77
66
 
67
+ ## Command
68
+
78
69
  ```bash
79
70
  $ bundle exec rake routes:oas:docs
80
71
  ```
@@ -1,20 +1,27 @@
1
- ## Use Schema Namespace (default)
1
+ # Use Schema Namespace
2
+
3
+ ## Prepare
4
+
5
+ Add this line to your application's Gemfile:
2
6
 
3
7
  ```ruby
8
+ group :development do
9
+ gem 'r2-oas'
10
+ end
11
+ ```
4
12
 
13
+ Add the following settings to your rails project's `config/environments/development.rb`.
14
+
15
+ ```ruby
5
16
  require 'r2-oas'
6
17
 
7
18
  R2OAS.configure do |config|
8
- # default setting
9
- config.root_dir_path = "./oas_docs"
10
- config.schema_save_dir_name = "src"
11
- config.doc_save_file_name = "oas_doc.yml"
12
- # default
13
- config.use_tag_namespace = true
14
- config.use_schema_namespace = true # write here
15
- end
19
+ config.use_schema_namespace = true
20
+ end
16
21
  ```
17
22
 
23
+ ## Command
24
+
18
25
  ```bash
19
26
  $ bundle exec rake routes:oas:docs
20
27
  ```
@@ -1,20 +1,27 @@
1
- ## Use Tag Namespace (default)
1
+ # Use Tag Namespace
2
+
3
+ ## Prepare
4
+
5
+ Add this line to your application's Gemfile:
2
6
 
3
7
  ```ruby
8
+ group :development do
9
+ gem 'r2-oas'
10
+ end
11
+ ```
12
+
13
+ Add the following settings to your rails project's `config/environments/development.rb`.
4
14
 
15
+ ```ruby
5
16
  require 'r2-oas'
6
17
 
7
18
  R2OAS.configure do |config|
8
- # default setting
9
- config.root_dir_path = "./oas_docs"
10
- config.schema_save_dir_name = "src"
11
- config.doc_save_file_name = "oas_doc.yml"
12
- # default
13
- config.use_tag_namespace = true # write here
14
- config.use_schema_namespace = true
15
- end
19
+ config.use_tag_namespace = true
20
+ end
16
21
  ```
17
22
 
23
+ ## Command
24
+
18
25
  ```bash
19
26
  $ bundle exec rake routes:oas:docs
20
27
  ```
@@ -121,22 +128,21 @@ oas_docs
121
128
  └── oas_doc.yml
122
129
  ```
123
130
 
124
- ## Do not Use Tag Namespace
131
+ # Do not Use Tag Namespace
132
+
133
+ ## Prepare
125
134
 
126
135
  ```ruby
127
136
 
128
137
  require 'r2-oas'
129
138
 
130
139
  R2OAS.configure do |config|
131
- # default setting
132
- config.root_dir_path = "./oas_docs"
133
- config.schema_save_dir_name = "src"
134
- config.doc_save_file_name = "oas_doc.yml"
135
- config.use_tag_namespace = false # write here
136
- config.use_schema_namespace = true
140
+ config.use_tag_namespace = false
137
141
  end
138
142
  ```
139
143
 
144
+ ## Command
145
+
140
146
  ```bash
141
147
  $ bundle exec rake routes:oas:docs
142
148
  ```
@@ -1,17 +1,17 @@
1
- ## Basic Usage
1
+ # View docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
8
- # default setting
9
- config.root_dir_path = "./oas_docs"
10
- config.schema_save_dir_name = "src"
11
- config.doc_save_file_name = "oas_doc.yml"
7
+ ```ruby
8
+ group :development do
9
+ gem 'r2-oas'
12
10
  end
13
11
  ```
14
12
 
13
+ ## Command
14
+
15
15
  ```bash
16
16
  $ bundle exec rake routes:oas:ui
17
17
  ```
@@ -185,10 +185,10 @@ When you press `Ctrl + C` , the ui closes and the following message appears.
185
185
  I, [2019-04-29T12:54:14.333082 #10516] INFO -- : [R2-OAS] end
186
186
  ```
187
187
 
188
- ## Advanced Usage
188
+ ## Use PATHS_FILE environment
189
189
 
190
190
  If you want to generate docs by squeezing unit paths (For example, `api/v1/task.yml`),
191
- you set PATHS_FILE environment like this:
191
+ you set `PATHS_FILE` environment like this:
192
192
 
193
193
  ```bash
194
194
  $ PATHS_FILE="../oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:editor
@@ -40,11 +40,12 @@ module R2OAS
40
40
  }
41
41
  }
42
42
  DEFAULT_HTTP_METHODS_WHEN_GENERATE_REQUEST_BODY = %w[post patch put]
43
+ DEFAULT_IGNORED_HTTP_STATUSES_WHEN_GENERATE_COMPONENT_SCHEMA = %w[204 404]
43
44
  # rubocop:enable Style/MutableConstant
44
45
  DEFAULT_TOOL = Tool.new
45
46
  # :dot or :underbar
46
47
  DEFAULT_NAMESPACE_TYPE = :underbar
47
- DEFAULT_DEPLOY_DIR_PATH = "./deploy_docs"
48
+ DEFAULT_DEPLOY_DIR_PATH = './deploy_docs'
48
49
 
49
50
  PUBLIC_VALID_OPTIONS_KEYS = %i[
50
51
  version
@@ -59,6 +60,7 @@ module R2OAS
59
60
  swagger
60
61
  http_statuses_when_http_method
61
62
  http_methods_when_generate_request_body
63
+ ignored_http_statuses_when_generate_component_schema
62
64
  tool
63
65
  namespace_type
64
66
  deploy_dir_path
@@ -82,21 +84,22 @@ module R2OAS
82
84
  private
83
85
 
84
86
  module_function def set_default(target)
85
- target.version = DEFAULT_VERSION
86
- target.root_dir_path = DEFAULT_ROOT_DIR_PATH
87
- target.schema_save_dir_name = DEFAULT_SCHEMA_SAVE_DIR_NAME
88
- target.doc_save_file_name = DEFAULT_DOC_SAVE_FILE_NAME
89
- target.force_update_schema = DEFAULT_FORCE_UPDATE_SCHEMA
90
- target.use_tag_namespace = DEFAULT_USE_TAG_NAMESPACE
91
- target.use_schema_namespace = DEFAULT_USE_SCHEMA_NAMESPACE
92
- target.server = DEFAULT_SERVER
93
- target.interval_to_save_edited_tmp_schema = DEFAULT_INTERVAL_TO_SAVE_EDITED_TMP_SCHEMA
94
- target.swagger = DEFAULT_SWAGGER
95
- target.http_statuses_when_http_method = DEFAULT_HTTP_STATUSES_WHEN_HTTP_METHOD
96
- target.tool = DEFAULT_TOOL
97
- target.http_methods_when_generate_request_body = DEFAULT_HTTP_METHODS_WHEN_GENERATE_REQUEST_BODY
98
- target.namespace_type = DEFAULT_NAMESPACE_TYPE
99
- target.deploy_dir_path = DEFAULT_DEPLOY_DIR_PATH
87
+ target.version = DEFAULT_VERSION
88
+ target.root_dir_path = DEFAULT_ROOT_DIR_PATH
89
+ target.schema_save_dir_name = DEFAULT_SCHEMA_SAVE_DIR_NAME
90
+ target.doc_save_file_name = DEFAULT_DOC_SAVE_FILE_NAME
91
+ target.force_update_schema = DEFAULT_FORCE_UPDATE_SCHEMA
92
+ target.use_tag_namespace = DEFAULT_USE_TAG_NAMESPACE
93
+ target.use_schema_namespace = DEFAULT_USE_SCHEMA_NAMESPACE
94
+ target.server = DEFAULT_SERVER
95
+ target.interval_to_save_edited_tmp_schema = DEFAULT_INTERVAL_TO_SAVE_EDITED_TMP_SCHEMA
96
+ target.swagger = DEFAULT_SWAGGER
97
+ target.http_statuses_when_http_method = DEFAULT_HTTP_STATUSES_WHEN_HTTP_METHOD
98
+ target.tool = DEFAULT_TOOL
99
+ target.http_methods_when_generate_request_body = DEFAULT_HTTP_METHODS_WHEN_GENERATE_REQUEST_BODY
100
+ target.ignored_http_statuses_when_generate_component_schema = DEFAULT_IGNORED_HTTP_STATUSES_WHEN_GENERATE_COMPONENT_SCHEMA
101
+ target.namespace_type = DEFAULT_NAMESPACE_TYPE
102
+ target.deploy_dir_path = DEFAULT_DEPLOY_DIR_PATH
100
103
  end
101
104
  end
102
105
  end
@@ -25,7 +25,7 @@ module R2OAS
25
25
  end
26
26
 
27
27
  def copy_swagger_ui_index
28
- index_path = File.expand_path(Rails.root.join(deploy_dir_path, "index.html"), __FILE__)
28
+ index_path = File.expand_path(Rails.root.join(deploy_dir_path, 'index.html'), __FILE__)
29
29
  @schema_file_path = doc_save_file_name
30
30
  template_path = File.expand_path('swagger-ui/index.html.erb', __dir__)
31
31
  template = File.read(template_path)
@@ -64,18 +64,26 @@ module R2OAS
64
64
 
65
65
  def responses_when_http_status
66
66
  http_statuses.each_with_object({}) do |http_status, result|
67
- result.deep_merge!(
68
- http_status => {
69
- 'description' => "#{@tag_name} description",
70
- 'content' => {
71
- 'application/json' => {
72
- 'schema' => {
73
- '$ref' => "#/components/schemas/#{_components_schema_name(http_status)}"
67
+ if ignored_http_statuses_when_generate_component_schema.include?(http_status)
68
+ result.deep_merge!(
69
+ http_status => {
70
+ 'description' => "#{@tag_name} description"
71
+ }
72
+ )
73
+ else
74
+ result.deep_merge!(
75
+ http_status => {
76
+ 'description' => "#{@tag_name} description",
77
+ 'content' => {
78
+ 'application/json' => {
79
+ 'schema' => {
80
+ '$ref' => "#/components/schemas/#{_components_schema_name(http_status)}"
81
+ }
74
82
  }
75
83
  }
76
84
  }
77
- }
78
- )
85
+ )
86
+ end
79
87
  end
80
88
  end
81
89
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module R2OAS
4
- VERSION = '0.1.0'
4
+ VERSION = '0.1.2'
5
5
  end
@@ -10,24 +10,10 @@ Gem::Specification.new do |spec|
10
10
  spec.authors = ['yukihirop']
11
11
  spec.email = ['te108186@gmail.com']
12
12
 
13
- spec.summary = 'Generate api docment(OpenAPI) side only from rails routing.'
14
- spec.description = <<~EOF
15
- Generate api docment(OpenAPI) side only from `rails` routing.
16
- Provides a rake command to help `generate` , `view` , and `edit` OpenAPI documents.
13
+ spec.summary = 'Provide rake tasks to management API Docment (OpenAPI)'
14
+ spec.description = "Let's intuitively write API documentation with Swagger Editor in your Rails Project! 😊"
17
15
 
18
- ```
19
- bundle exec rake routes:oas:docs # generate
20
- bundle exec rake routes:oas:ui # view
21
- bundle exec rake routes:oas:editor # edit
22
- bundle exec rake routes:oas:monitor # monitor
23
- bundle exec rake routes:oas:dist # distribute
24
- bundle exec rake routes:oas:clean # clean
25
- bundle exec rake routes:oas:analyze # analyze
26
- bundle exec rake routes:oas:deploy # deploy
27
- ```
28
- EOF
29
-
30
- spec.homepage = 'https://github.com/yukihirop/r2-oas'
16
+ spec.homepage = 'https://yukihirop.github.io/r2-oas'
31
17
  spec.license = 'MIT'
32
18
 
33
19
  # Specify which files should be added to the gem when it is released.
@@ -48,9 +34,9 @@ Gem::Specification.new do |spec|
48
34
  spec.add_runtime_dependency 'terminal-table', '~> 1.6.0'
49
35
  spec.add_runtime_dependency 'watir', '~> 6.0'
50
36
  spec.add_development_dependency 'bundler', '~> 1.17'
37
+ spec.add_development_dependency 'coveralls'
51
38
  spec.add_development_dependency 'pry'
52
- spec.add_development_dependency 'rake', '~> 10.0'
39
+ spec.add_development_dependency 'rake', '~> 13.0'
53
40
  spec.add_development_dependency 'rspec', '~> 3.0'
54
41
  spec.add_development_dependency 'rubocop'
55
- spec.add_development_dependency 'coveralls'
56
42
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: r2-oas
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - yukihirop
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2019-10-22 00:00:00.000000000 Z
11
+ date: 2020-04-22 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: docker-api
@@ -123,7 +123,7 @@ dependencies:
123
123
  - !ruby/object:Gem::Version
124
124
  version: '1.17'
125
125
  - !ruby/object:Gem::Dependency
126
- name: pry
126
+ name: coveralls
127
127
  requirement: !ruby/object:Gem::Requirement
128
128
  requirements:
129
129
  - - ">="
@@ -137,49 +137,49 @@ dependencies:
137
137
  - !ruby/object:Gem::Version
138
138
  version: '0'
139
139
  - !ruby/object:Gem::Dependency
140
- name: rake
140
+ name: pry
141
141
  requirement: !ruby/object:Gem::Requirement
142
142
  requirements:
143
- - - "~>"
143
+ - - ">="
144
144
  - !ruby/object:Gem::Version
145
- version: '10.0'
145
+ version: '0'
146
146
  type: :development
147
147
  prerelease: false
148
148
  version_requirements: !ruby/object:Gem::Requirement
149
149
  requirements:
150
- - - "~>"
150
+ - - ">="
151
151
  - !ruby/object:Gem::Version
152
- version: '10.0'
152
+ version: '0'
153
153
  - !ruby/object:Gem::Dependency
154
- name: rspec
154
+ name: rake
155
155
  requirement: !ruby/object:Gem::Requirement
156
156
  requirements:
157
157
  - - "~>"
158
158
  - !ruby/object:Gem::Version
159
- version: '3.0'
159
+ version: '13.0'
160
160
  type: :development
161
161
  prerelease: false
162
162
  version_requirements: !ruby/object:Gem::Requirement
163
163
  requirements:
164
164
  - - "~>"
165
165
  - !ruby/object:Gem::Version
166
- version: '3.0'
166
+ version: '13.0'
167
167
  - !ruby/object:Gem::Dependency
168
- name: rubocop
168
+ name: rspec
169
169
  requirement: !ruby/object:Gem::Requirement
170
170
  requirements:
171
- - - ">="
171
+ - - "~>"
172
172
  - !ruby/object:Gem::Version
173
- version: '0'
173
+ version: '3.0'
174
174
  type: :development
175
175
  prerelease: false
176
176
  version_requirements: !ruby/object:Gem::Requirement
177
177
  requirements:
178
- - - ">="
178
+ - - "~>"
179
179
  - !ruby/object:Gem::Version
180
- version: '0'
180
+ version: '3.0'
181
181
  - !ruby/object:Gem::Dependency
182
- name: coveralls
182
+ name: rubocop
183
183
  requirement: !ruby/object:Gem::Requirement
184
184
  requirements:
185
185
  - - ">="
@@ -192,20 +192,8 @@ dependencies:
192
192
  - - ">="
193
193
  - !ruby/object:Gem::Version
194
194
  version: '0'
195
- description: |
196
- Generate api docment(OpenAPI) side only from `rails` routing.
197
- Provides a rake command to help `generate` , `view` , and `edit` OpenAPI documents.
198
-
199
- ```
200
- bundle exec rake routes:oas:docs # generate
201
- bundle exec rake routes:oas:ui # view
202
- bundle exec rake routes:oas:editor # edit
203
- bundle exec rake routes:oas:monitor # monitor
204
- bundle exec rake routes:oas:dist # distribute
205
- bundle exec rake routes:oas:clean # clean
206
- bundle exec rake routes:oas:analyze # analyze
207
- bundle exec rake routes:oas:deploy # deploy
208
- ```
195
+ description: "Let's intuitively write API documentation with Swagger Editor in your
196
+ Rails Project! \U0001F60A"
209
197
  email:
210
198
  - te108186@gmail.com
211
199
  executables: []
@@ -229,19 +217,27 @@ files:
229
217
  - Rakefile
230
218
  - bin/console
231
219
  - bin/setup
232
- - docs/HOW_TO_ANALYZE_DOCS.md
233
- - docs/HOW_TO_CLEAN_DOCS.md
234
- - docs/HOW_TO_DEPLOY_SWAGGER_DOC.md
235
- - docs/HOW_TO_DISPLAY_PATHS_LIST.md
236
- - docs/HOW_TO_DISPLAY_PATHS_STATS.md
237
- - docs/HOW_TO_GENERATE_DOCS.md
238
- - docs/HOW_TO_MONITOR_SWAGGER_DOC.md
239
- - docs/HOW_TO_START_SWAGGER_EDITOR.md
240
- - docs/HOW_TO_START_SWAGGER_UI.md
241
- - docs/HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md
242
- - docs/HOW_TO_USE_SCHEMA_NAMESPACE.md
243
- - docs/HOW_TO_USE_TAG_NAMESPACE.md
244
- - docs/versions/v3.md
220
+ - docs/.nojekyll
221
+ - docs/README.md
222
+ - docs/_sidebar.md
223
+ - docs/index.html
224
+ - docs/schema/3.0.0.md
225
+ - docs/setting/COC.md
226
+ - docs/setting/CORS.md
227
+ - docs/setting/configure.md
228
+ - docs/usage/analyze_docs.md
229
+ - docs/usage/clean_docs.md
230
+ - docs/usage/deploy_docs.md
231
+ - docs/usage/display_paths_list.md
232
+ - docs/usage/display_paths_stats.md
233
+ - docs/usage/edit_docs.md
234
+ - docs/usage/generate_docs.md
235
+ - docs/usage/monitor_docs.md
236
+ - docs/usage/use_hook_methods.md
237
+ - docs/usage/use_hook_to_generate_docs.md
238
+ - docs/usage/use_schema_namespace.md
239
+ - docs/usage/use_tag_namespace.md
240
+ - docs/usage/view_docs.md
245
241
  - lib/r2-oas.rb
246
242
  - lib/r2-oas/app_configuration.rb
247
243
  - lib/r2-oas/app_configuration/server.rb
@@ -346,7 +342,7 @@ files:
346
342
  - lib/r2-oas/tool/paths/stats.rb
347
343
  - lib/r2-oas/version.rb
348
344
  - r2-oas.gemspec
349
- homepage: https://github.com/yukihirop/r2-oas
345
+ homepage: https://yukihirop.github.io/r2-oas
350
346
  licenses:
351
347
  - MIT
352
348
  metadata: {}
@@ -369,5 +365,5 @@ rubyforge_project:
369
365
  rubygems_version: 2.7.6
370
366
  signing_key:
371
367
  specification_version: 4
372
- summary: Generate api docment(OpenAPI) side only from rails routing.
368
+ summary: Provide rake tasks to management API Docment (OpenAPI)
373
369
  test_files: []