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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +13 -1
- data/Gemfile.lock +85 -70
- data/README.ja.md +11 -413
- data/README.md +9 -409
- data/docs/.nojekyll +0 -0
- data/docs/README.md +326 -0
- data/docs/_sidebar.md +22 -0
- data/docs/index.html +28 -0
- data/docs/{versions/v3.md → schema/3.0.0.md} +1 -1
- data/docs/setting/COC.md +14 -0
- data/docs/setting/CORS.md +22 -0
- data/docs/setting/configure.md +163 -0
- data/docs/{HOW_TO_ANALYZE_DOCS.md → usage/analyze_docs.md} +8 -8
- data/docs/usage/clean_docs.md +19 -0
- data/docs/{HOW_TO_DEPLOY_SWAGGER_DOC.md → usage/deploy_docs.md} +8 -8
- data/docs/{HOW_TO_DISPLAY_PATHS_LIST.md → usage/display_paths_list.md} +15 -8
- data/docs/{HOW_TO_DISPLAY_PATHS_STATS.md → usage/display_paths_stats.md} +15 -14
- data/docs/{HOW_TO_START_SWAGGER_EDITOR.md → usage/edit_docs.md} +10 -10
- data/docs/{HOW_TO_GENERATE_DOCS.md → usage/generate_docs.md} +9 -9
- data/docs/{HOW_TO_MONITOR_SWAGGER_DOC.md → usage/monitor_docs.md} +9 -9
- data/docs/usage/use_hook_methods.md +236 -0
- data/docs/{HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md → usage/use_hook_to_generate_docs.md} +6 -15
- data/docs/{HOW_TO_USE_SCHEMA_NAMESPACE.md → usage/use_schema_namespace.md} +16 -9
- data/docs/{HOW_TO_USE_TAG_NAMESPACE.md → usage/use_tag_namespace.md} +22 -16
- data/docs/{HOW_TO_START_SWAGGER_UI.md → usage/view_docs.md} +10 -10
- data/lib/r2-oas/app_configuration.rb +19 -16
- data/lib/r2-oas/deploy/client.rb +1 -1
- data/lib/r2-oas/schema/v3/object/path_item_object.rb +17 -9
- data/lib/r2-oas/version.rb +1 -1
- data/r2-oas.gemspec +5 -19
- metadata +42 -46
- data/docs/HOW_TO_CLEAN_DOCS.md +0 -19
data/docs/.nojekyll
ADDED
File without changes
|
data/docs/README.md
ADDED
@@ -0,0 +1,326 @@
|
|
1
|
+
# R2-OAS
|
2
|
+
|
3
|
+
[](https://travis-ci.org/yukihirop/r2-oas)
|
4
|
+
[](https://coveralls.io/github/yukihirop/r2-oas)
|
5
|
+
[](https://codeclimate.com/github/yukihirop/r2-oas/maintainability)
|
6
|
+
|
7
|
+
Generate api docment(OpenAPI) side only from `Rails` routing.
|
8
|
+
|
9
|
+
Provides a rake command to help `generate` , `view` , and `edit` OpenAPI documents.
|
10
|
+
|
11
|
+
```bash
|
12
|
+
bundle exec rake routes:oas:docs # generate
|
13
|
+
bundle exec rake routes:oas:ui # view
|
14
|
+
bundle exec rake routes:oas:editor # edit
|
15
|
+
bundle exec rake routes:oas:monitor # monitor
|
16
|
+
bundle exec rake routes:oas:dist # distribute
|
17
|
+
bundle exec rake routes:oas:clean # clean
|
18
|
+
bundle exec rake routes:oas:analyze # analyze
|
19
|
+
bundle exec rake routes:oas:deploy # deploy
|
20
|
+
```
|
21
|
+
|
22
|
+
## 💎 Installation
|
23
|
+
|
24
|
+
Add this line to your application's Gemfile:
|
25
|
+
|
26
|
+
```ruby
|
27
|
+
group :development do
|
28
|
+
gem 'r2-oas'
|
29
|
+
end
|
30
|
+
```
|
31
|
+
|
32
|
+
And then execute:
|
33
|
+
|
34
|
+
$ bundle
|
35
|
+
|
36
|
+
Or install it yourself as:
|
37
|
+
|
38
|
+
$ gem install r2-oas
|
39
|
+
|
40
|
+
## 🔦 Requirements
|
41
|
+
|
42
|
+
If you want to view with `Swagger UI` or edit with `Swagger Editor`, This gem needs the following:
|
43
|
+
|
44
|
+
- [`swaggerapi/swagger-ui:latest` docker image](https://hub.docker.com/r/swaggerapi/swagger-ui/)
|
45
|
+
- [`swaggerapi/swagger-editor:latest` docker image](https://hub.docker.com/r/swaggerapi/swagger-editor/)
|
46
|
+
- [`chromedriver`](http://chromedriver.chromium.org/downloads)
|
47
|
+
|
48
|
+
If you do not have it download as below.
|
49
|
+
|
50
|
+
```
|
51
|
+
$ docker pull swaggerapi/swagger-editor:latest
|
52
|
+
$ docker pull swaggerapi/swagger-ui:latest
|
53
|
+
$ brew cask install chromedriver
|
54
|
+
```
|
55
|
+
|
56
|
+
## 🚀 Tutorial
|
57
|
+
|
58
|
+
After requiring a gem,
|
59
|
+
|
60
|
+
```bash
|
61
|
+
bundle exec routes:oas:docs
|
62
|
+
bundle exec routes:oas:editor
|
63
|
+
```
|
64
|
+
|
65
|
+
## 📖 Usage
|
66
|
+
|
67
|
+
All settings are optional. The initial value is as follows.
|
68
|
+
|
69
|
+
In your rails project, Write `config/environments/development.rb` like that:
|
70
|
+
|
71
|
+
```ruby
|
72
|
+
# default setting
|
73
|
+
R2OAS.configure do |config|
|
74
|
+
config.version = :v3
|
75
|
+
config.root_dir_path = "./oas_docs"
|
76
|
+
config.schema_save_dir_name = "src"
|
77
|
+
config.doc_save_file_name = "oas_doc.yml"
|
78
|
+
config.force_update_schema = false
|
79
|
+
config.use_tag_namespace = true
|
80
|
+
config.use_schema_namespace = false
|
81
|
+
config.interval_to_save_edited_tmp_schema = 15
|
82
|
+
# :dot or :underbar
|
83
|
+
config.namespace_type = :underbar
|
84
|
+
config.deploy_dir_path = "./deploy_docs"
|
85
|
+
|
86
|
+
config.server.data = [
|
87
|
+
{
|
88
|
+
url: "http://localhost:3000",
|
89
|
+
description: "localhost"
|
90
|
+
}
|
91
|
+
]
|
92
|
+
|
93
|
+
config.swagger.configure do |swagger|
|
94
|
+
swagger.ui.image = "swaggerapi/swagger-ui"
|
95
|
+
swagger.ui.port = "8080"
|
96
|
+
swagger.ui.exposed_port = "8080/tcp"
|
97
|
+
swagger.ui.volume = "/app/swagger.json"
|
98
|
+
swagger.editor.image = "swaggerapi/swagger-editor"
|
99
|
+
swagger.editor.port = "81"
|
100
|
+
swagger.editor.exposed_port = "8080/tcp"
|
101
|
+
end
|
102
|
+
|
103
|
+
config.use_object_classes = {
|
104
|
+
info_object: R2OAS::Schema::V3::InfoObject,
|
105
|
+
paths_object: R2OAS::Schema::V3::PathsObject,
|
106
|
+
path_item_object: R2OAS::Schema::V3::PathItemObject,
|
107
|
+
external_document_object: R2OAS::Schema::V3::ExternalDocumentObject,
|
108
|
+
components_object: R2OAS::Schema::V3::ComponentsObject,
|
109
|
+
components_schema_object: R2OAS::Schema::V3::Components::SchemaObject,
|
110
|
+
components_request_body_object: R2OAS::Schema::V3::Components::RequestBodyObject
|
111
|
+
}
|
112
|
+
|
113
|
+
config.http_statuses_when_http_method = {
|
114
|
+
get: {
|
115
|
+
default: %w(200 422),
|
116
|
+
path_parameter: %w(200 404 422)
|
117
|
+
},
|
118
|
+
post: {
|
119
|
+
default: %w(201 422),
|
120
|
+
path_parameter: %w(201 404 422)
|
121
|
+
},
|
122
|
+
patch: {
|
123
|
+
default: %w(204 422),
|
124
|
+
path_parameter: %w(204 404 422)
|
125
|
+
},
|
126
|
+
put: {
|
127
|
+
default: %w(204 422),
|
128
|
+
path_parameter: %w(204 404 422)
|
129
|
+
},
|
130
|
+
delete: {
|
131
|
+
default: %w(200 422),
|
132
|
+
path_parameter: %w(200 404 422)
|
133
|
+
}
|
134
|
+
}
|
135
|
+
|
136
|
+
config.http_methods_when_generate_request_body = %w[post patch put]
|
137
|
+
config.ignored_http_statuses_when_generate_component_schema = %w[204 404]
|
138
|
+
|
139
|
+
config.tool.paths_stats.configure do |paths_stats|
|
140
|
+
paths_stats.month_to_turn_to_warning_color = 3
|
141
|
+
paths_stats.warning_color = :red
|
142
|
+
paths_stats.table_title_color = :yellow
|
143
|
+
paths_stats.heading_color = :yellow
|
144
|
+
paths_stats.highlight_color = :magenta
|
145
|
+
end
|
146
|
+
end
|
147
|
+
```
|
148
|
+
|
149
|
+
You can execute the following command in the root directory of rails.
|
150
|
+
|
151
|
+
```bash
|
152
|
+
$ # Generate docs
|
153
|
+
$ bundle exec rake routes:oas:docs # Generate docs
|
154
|
+
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:docs # Generate docs by specify unit paths
|
155
|
+
|
156
|
+
$ # Start swagger editor
|
157
|
+
$ bundle exec rake routes:oas:editor # Start swagger editor
|
158
|
+
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:editor # Start swagger editor by specify unit paths
|
159
|
+
$ # Start swagger ui
|
160
|
+
$ bundle exec rake routes:oas:ui # Start swagger ui
|
161
|
+
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:ui # Start swagger ui by specify unit paths
|
162
|
+
$ # Monitor swagger document
|
163
|
+
$ bundle exec rake routes:oas:monitor # Monitor swagger document
|
164
|
+
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:monitor # Monitor swagger by specify unit paths
|
165
|
+
|
166
|
+
$ # Analyze docs
|
167
|
+
$ OAS_FILE="~/Desktop/swagger.yml" bundle exec rake routes:oas:analyze
|
168
|
+
$ # Clean docs
|
169
|
+
$ bundle exec rake routes:oas:clean
|
170
|
+
$ # Deploy docs
|
171
|
+
$ bundle exec rake routes:oas:deploy
|
172
|
+
$ # Distribute swagger document
|
173
|
+
$ bundle exec rake routes:oas:dist
|
174
|
+
$ # Distribute swagger document
|
175
|
+
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:dist # Distribute swagger document by specify unit paths
|
176
|
+
|
177
|
+
# Display paths list
|
178
|
+
$ bundle exec rake routes:oas:paths_ls
|
179
|
+
# Display paths stats
|
180
|
+
$ bundle exec rake routes:oas:paths_stats
|
181
|
+
```
|
182
|
+
|
183
|
+
## ❤️ Support Rails Version
|
184
|
+
|
185
|
+
- Rails (>= 4.2.5.1)
|
186
|
+
|
187
|
+
## ❤️ Support Ruby Version
|
188
|
+
|
189
|
+
- Ruby (>= 2.3.3p222 (2016-11-21 revision 56859) [x86_64-darwin18])
|
190
|
+
|
191
|
+
## ❤️ Support Rouging
|
192
|
+
|
193
|
+
- Rails Engine Routing
|
194
|
+
- Rails Normal Routing
|
195
|
+
|
196
|
+
## ❗️ Convention over Configuration (CoC)
|
197
|
+
|
198
|
+
- `tag name` represents `controller name` and determine `paths file name`.
|
199
|
+
- For example, If `controller name` is `Api::V1::UsersController`, `tag_name` is `api/v1/user`. and `paths file name` is `api/v1/user.yml`
|
200
|
+
|
201
|
+
- `_` of `components/{schemas,requestBodies, ...} name` convert `/` when save file.
|
202
|
+
- For example, If `components/schemas name` is `Api_V1_User`, `components/schemas file name` is `api/v1/user.yml`.
|
203
|
+
- `_` is supposed to be used to express `namespace`.
|
204
|
+
- format is `Namespace1_Namespace2_Model`.
|
205
|
+
|
206
|
+
- `.` of `components/{schemas,requestBodies, ...} name` convert `/` when save file.
|
207
|
+
- For example, If `components/schemas name` is `api.v1.User`, `components/schemas file name` is `api/v1/user.yml`.
|
208
|
+
- `.` is supposed to be used to express `namespace`.
|
209
|
+
- format is `namespace1.namespace2.Model`.
|
210
|
+
|
211
|
+
## ⚙ Configure
|
212
|
+
|
213
|
+
we explain the options that can be set.
|
214
|
+
|
215
|
+
#### basic
|
216
|
+
|
217
|
+
|option|description|default|
|
218
|
+
|------|-----------|---|
|
219
|
+
|version|OpenAPI schema version| `:v3` |
|
220
|
+
|root_dir_path|Root directory for storing products.| `"./oas_docs"` |
|
221
|
+
|schema_save_dir_name|Directory name for storing swagger schemas|`"src"`|
|
222
|
+
|doc_save_file_name|File name for storing swagger doc|`"oas_doc.yml"`|
|
223
|
+
|force_update_schema|Force update schema from routes data|`false`|
|
224
|
+
|use_tag_namespace|Use namespace for tag name|`true`|
|
225
|
+
|use_schema_namespace|Use namespace for schema name|`true`|
|
226
|
+
|interval_to_save_edited_tmp_schema|Interval(sec) to save edited tmp schema|`15`|
|
227
|
+
|http_statuses_when_http_method|Determine the response to support for each HTTP method|omission...|
|
228
|
+
|http_methods_when_generate_request_body|HTTP methods when generate requestBody|`[post put patch]`|
|
229
|
+
|ignored_http_statuses_when_generate_component_schema|Ignore HTTP statuses when generate component schema|`[204 404]`|
|
230
|
+
|namespace_type|namespace for components(schemas/requestBodies) name| `underbar` |
|
231
|
+
|deploy_dir_path|deploy directory.|`"./deploy_docs"`|
|
232
|
+
|
233
|
+
#### server
|
234
|
+
|
235
|
+
|option|children option|description|default|
|
236
|
+
|------|---------------|-----------|-------|
|
237
|
+
|server|data|Server data (url, description) |[{ url: `http://localhost:3000`, description: `localhost` }] |
|
238
|
+
|
239
|
+
#### swagger
|
240
|
+
|
241
|
+
|option|children option|grandchild option|description|default|
|
242
|
+
|------|---------------|-----------------|-----------|-------|
|
243
|
+
|swagger|ui|image|Swagger UI Docker Image|`"swaggerapi/swagger-ui"`|
|
244
|
+
|swagger|ui|port|Swagger UI Port|`"8080"`|
|
245
|
+
|swagger|ui|exposed_port|Swagger UI Exposed Port|`"8080/tcp"`|
|
246
|
+
|swagger|ui|volume|Swagger UI Volume|`"/app/swagger.json"`|
|
247
|
+
|swagger|editor|image|Swagger Editor Docker Image|`"swaggerapi/swagger-editor"`|
|
248
|
+
|swagger|editor|port|Swagger Editor Port|`"8080"`|
|
249
|
+
|swagger|editor|exposed_port|Swagger Editor Exposed Port|`"8080/tcp"`|
|
250
|
+
|
251
|
+
#### hook
|
252
|
+
|
253
|
+
|option|description|default|
|
254
|
+
|------|-----------|-------|
|
255
|
+
|use_object_classes|Object class(hook class) to generate Openapi document|{ info_object: `R2OAS::Schema::V3::InfoObject`,<br>paths_object: `R2OAS::Schema::V3::PathsObject`,<br>path_item_object: `R2OAS::Schema::V3::PathItemObject`, external_document_object: `R2OAS::Schema::V3::ExternalDocumentObject`,<br> components_object: `R2OAS::Schema::V3::ComponentsObject`,<br> components_schema_object: `R2OAS::Schema::V3::Components::SchemaObject`, <br> components_request_body_object:`R2OAS::Schema::V3::Components::RequestBodyObject` }|
|
256
|
+
|
257
|
+
#### tool
|
258
|
+
|
259
|
+
|option|children option|grandchild option|description|default|
|
260
|
+
|------|---------------|-----------------|-----------|-------|
|
261
|
+
|tool|paths_stats|month_to_turn_to_warning_color|Elapsed month to issue a warning|`3`|
|
262
|
+
|tool|paths_stats|warning_color|Warning Color|`:red`|
|
263
|
+
|tool|paths_stats|table_title_color|Table Title Color|`:yellow`|
|
264
|
+
|tool|paths_stats|heading_color|Heading Color|`:yellow`|
|
265
|
+
|tool|paths_stats|highlight_color|Highlight Color|`:magenta`|
|
266
|
+
|
267
|
+
Please refer to [here](https://github.com/janlelis/paint) for the color.
|
268
|
+
|
269
|
+
## Environment variables
|
270
|
+
|
271
|
+
We explain the environment variables that can be set.
|
272
|
+
|
273
|
+
|variable|description|default|
|
274
|
+
|--------|-----------|-------|
|
275
|
+
|PATHS_FILE|Specify one paths file path|`""`|
|
276
|
+
|OAS_FILE|Specify swagger file path to analyze|`""`|
|
277
|
+
|
278
|
+
|
279
|
+
## .paths
|
280
|
+
|
281
|
+
Writing file paths in .paths will only read them.
|
282
|
+
You can comment out with `#`
|
283
|
+
|
284
|
+
`oas_docs/.paths`
|
285
|
+
|
286
|
+
```
|
287
|
+
#account_user_role.yml # ignore
|
288
|
+
account.yml
|
289
|
+
account.yml # ignore
|
290
|
+
account.yml # ignore
|
291
|
+
```
|
292
|
+
|
293
|
+
## 🔩 CORS
|
294
|
+
|
295
|
+
Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
|
296
|
+
|
297
|
+
```ruby
|
298
|
+
require 'rack/cors'
|
299
|
+
use Rack::Cors do
|
300
|
+
allow do
|
301
|
+
origins '*'
|
302
|
+
resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
|
303
|
+
end
|
304
|
+
end
|
305
|
+
```
|
306
|
+
|
307
|
+
Alternatively you can set CORS headers in a `before` block.
|
308
|
+
|
309
|
+
```ruby
|
310
|
+
before do
|
311
|
+
header['Access-Control-Allow-Origin'] = '*'
|
312
|
+
header['Access-Control-Request-Method'] = '*'
|
313
|
+
end
|
314
|
+
```
|
315
|
+
|
316
|
+
## 📝 License
|
317
|
+
|
318
|
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
319
|
+
|
320
|
+
## 🤝 Contributing
|
321
|
+
|
322
|
+
1. Fork it ( http://github.com/yukihirop/r2-oas/fork )
|
323
|
+
2. Create your feature branch (`git checkout -b my-new-feature`)
|
324
|
+
3. Commit your changes (`git commit -am 'Add some feature'`)
|
325
|
+
4. Push to the branch (`git push origin my-new-feature`)
|
326
|
+
5. Create new Pull Request
|
data/docs/_sidebar.md
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
<!-- docs/_sidebar.md -->
|
2
|
+
|
3
|
+
* **Usage**
|
4
|
+
* [Generate Docs](/usage/generate_docs)
|
5
|
+
* [Edit docs](/usage/edit_docs)
|
6
|
+
* [View docs](/usage/view_docs)
|
7
|
+
* [Monitor Docs](/usage/monitor_docs)
|
8
|
+
* [Analyze Docs](/usage/analyze_docs)
|
9
|
+
* [Use Hook to Generate Docs](/usage/use_hook_to_generate_docs)
|
10
|
+
* [Use schema namespace](/usage/use_schema_namespace)
|
11
|
+
* [Use tag namespace](/usage/use_tag_namespace)
|
12
|
+
* [Use hook methods](/usage/use_hook_methods)
|
13
|
+
* [Deploy docs](/usage/deploy_docs)
|
14
|
+
* [Clean Docs](/usage/clean_docs)
|
15
|
+
* [Display Paths Lists](/usage/display_paths_list)
|
16
|
+
* [Display Paths Stats](/usage/display_paths_stats)
|
17
|
+
* **Configure**
|
18
|
+
* [COC](/setting/COC)
|
19
|
+
* [Configure](/setting/configure)
|
20
|
+
* [CORS](/setting/CORS)
|
21
|
+
* **Support Schema**
|
22
|
+
* [3.0.0](/schema/3.0.0)
|
data/docs/index.html
ADDED
@@ -0,0 +1,28 @@
|
|
1
|
+
<!DOCTYPE html>
|
2
|
+
<html lang="en">
|
3
|
+
<head>
|
4
|
+
<meta charset="UTF-8">
|
5
|
+
<title>Document</title>
|
6
|
+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
7
|
+
<meta name="description" content="Description">
|
8
|
+
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
9
|
+
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
|
10
|
+
</head>
|
11
|
+
<body>
|
12
|
+
<div id="app"></div>
|
13
|
+
<script>
|
14
|
+
window.$docsify = {
|
15
|
+
auto2top: true,
|
16
|
+
name: '<span>r2-oas</span>',
|
17
|
+
repo: 'https://github.com/yukihirop/r2-oas',
|
18
|
+
loadSidebar: true,
|
19
|
+
subMaxLevel: 2
|
20
|
+
}
|
21
|
+
</script>
|
22
|
+
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
23
|
+
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
24
|
+
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
|
25
|
+
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-ruby.min.js"></script>
|
26
|
+
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
|
27
|
+
</body>
|
28
|
+
</html>
|
data/docs/setting/COC.md
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
# ❗️Convention over Configuration (CoC)
|
2
|
+
|
3
|
+
- `tag name` represents `controller name` and determine `paths file name`.
|
4
|
+
- For example, If `controller name` is `Api::V1::UsersController`, `tag_name` is `api/v1/user`. and `paths file name` is `api/v1/user.yml`
|
5
|
+
|
6
|
+
- `_` of `components/{schemas,requestBodies, ...} name` convert `/` when save file.
|
7
|
+
- For example, If `components/schemas name` is `Api_V1_User`, `components/schemas file name` is `api/v1/user.yml`.
|
8
|
+
- `_` is supposed to be used to express `namespace`.
|
9
|
+
- format is `Namespace1_Namespace2_Model`.
|
10
|
+
|
11
|
+
- `.` of `components/{schemas,requestBodies, ...} name` convert `/` when save file.
|
12
|
+
- For example, If `components/schemas name` is `api.v1.User`, `components/schemas file name` is `api/v1/user.yml`.
|
13
|
+
- `.` is supposed to be used to express `namespace`.
|
14
|
+
- format is `namespace1.namespace2.Model`.
|
@@ -0,0 +1,22 @@
|
|
1
|
+
# CORS
|
2
|
+
|
3
|
+
Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
|
4
|
+
|
5
|
+
```ruby
|
6
|
+
require 'rack/cors'
|
7
|
+
use Rack::Cors do
|
8
|
+
allow do
|
9
|
+
origins '*'
|
10
|
+
resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
|
11
|
+
end
|
12
|
+
end
|
13
|
+
```
|
14
|
+
|
15
|
+
Alternatively you can set CORS headers in a `before` block.
|
16
|
+
|
17
|
+
```ruby
|
18
|
+
before do
|
19
|
+
header['Access-Control-Allow-Origin'] = '*'
|
20
|
+
header['Access-Control-Request-Method'] = '*'
|
21
|
+
end
|
22
|
+
```
|
@@ -0,0 +1,163 @@
|
|
1
|
+
## Configure
|
2
|
+
|
3
|
+
All settings are `optional`. The initial value is as follows.
|
4
|
+
|
5
|
+
In your rails project, Write `config/environments/development.rb` like that:
|
6
|
+
|
7
|
+
```ruby
|
8
|
+
# default setting
|
9
|
+
R2OAS.configure do |config|
|
10
|
+
config.version = :v3
|
11
|
+
config.root_dir_path = "./oas_docs"
|
12
|
+
config.schema_save_dir_name = "src"
|
13
|
+
config.doc_save_file_name = "oas_doc.yml"
|
14
|
+
config.force_update_schema = false
|
15
|
+
config.use_tag_namespace = true
|
16
|
+
config.use_schema_namespace = false
|
17
|
+
config.interval_to_save_edited_tmp_schema = 15
|
18
|
+
# :dot or :underbar
|
19
|
+
config.namespace_type = :underbar
|
20
|
+
config.deploy_dir_path = "./deploy_docs"
|
21
|
+
|
22
|
+
config.server.data = [
|
23
|
+
{
|
24
|
+
url: "http://localhost:3000",
|
25
|
+
description: "localhost"
|
26
|
+
}
|
27
|
+
]
|
28
|
+
|
29
|
+
config.swagger.configure do |swagger|
|
30
|
+
swagger.ui.image = "swaggerapi/swagger-ui"
|
31
|
+
swagger.ui.port = "8080"
|
32
|
+
swagger.ui.exposed_port = "8080/tcp"
|
33
|
+
swagger.ui.volume = "/app/swagger.json"
|
34
|
+
swagger.editor.image = "swaggerapi/swagger-editor"
|
35
|
+
swagger.editor.port = "81"
|
36
|
+
swagger.editor.exposed_port = "8080/tcp"
|
37
|
+
end
|
38
|
+
|
39
|
+
config.use_object_classes = {
|
40
|
+
info_object: R2OAS::Schema::V3::InfoObject,
|
41
|
+
paths_object: R2OAS::Schema::V3::PathsObject,
|
42
|
+
path_item_object: R2OAS::Schema::V3::PathItemObject,
|
43
|
+
external_document_object: R2OAS::Schema::V3::ExternalDocumentObject,
|
44
|
+
components_object: R2OAS::Schema::V3::ComponentsObject,
|
45
|
+
components_schema_object: R2OAS::Schema::V3::Components::SchemaObject,
|
46
|
+
components_request_body_object: R2OAS::Schema::V3::Components::RequestBodyObject
|
47
|
+
}
|
48
|
+
|
49
|
+
config.http_statuses_when_http_method = {
|
50
|
+
get: {
|
51
|
+
default: %w(200 422),
|
52
|
+
path_parameter: %w(200 404 422)
|
53
|
+
},
|
54
|
+
post: {
|
55
|
+
default: %w(201 422),
|
56
|
+
path_parameter: %w(201 404 422)
|
57
|
+
},
|
58
|
+
patch: {
|
59
|
+
default: %w(204 422),
|
60
|
+
path_parameter: %w(204 404 422)
|
61
|
+
},
|
62
|
+
put: {
|
63
|
+
default: %w(204 422),
|
64
|
+
path_parameter: %w(204 404 422)
|
65
|
+
},
|
66
|
+
delete: {
|
67
|
+
default: %w(200 422),
|
68
|
+
path_parameter: %w(200 404 422)
|
69
|
+
}
|
70
|
+
}
|
71
|
+
|
72
|
+
config.http_methods_when_generate_request_body = %w[post patch put]
|
73
|
+
config.ignored_http_statuses_when_generate_component_schema = %w[204 404]
|
74
|
+
|
75
|
+
config.tool.paths_stats.configure do |paths_stats|
|
76
|
+
paths_stats.month_to_turn_to_warning_color = 3
|
77
|
+
paths_stats.warning_color = :red
|
78
|
+
paths_stats.table_title_color = :yellow
|
79
|
+
paths_stats.heading_color = :yellow
|
80
|
+
paths_stats.highlight_color = :magenta
|
81
|
+
end
|
82
|
+
end
|
83
|
+
```
|
84
|
+
|
85
|
+
we explain the options that can be set.
|
86
|
+
|
87
|
+
#### basic
|
88
|
+
|
89
|
+
|option|description|default|
|
90
|
+
|------|-----------|---|
|
91
|
+
|version|OpenAPI schema version| `:v3` |
|
92
|
+
|root_dir_path|Root directory for storing products.| `"./oas_docs"` |
|
93
|
+
|schema_save_dir_name|Directory name for storing swagger schemas|`"src"`|
|
94
|
+
|doc_save_file_name|File name for storing swagger doc|`"oas_doc.yml"`|
|
95
|
+
|force_update_schema|Force update schema from routes data|`false`|
|
96
|
+
|use_tag_namespace|Use namespace for tag name|`true`|
|
97
|
+
|use_schema_namespace|Use namespace for schema name|`true`|
|
98
|
+
|interval_to_save_edited_tmp_schema|Interval(sec) to save edited tmp schema|`15`|
|
99
|
+
|http_statuses_when_http_method|Determine the response to support for each HTTP method|omission...|
|
100
|
+
|http_methods_when_generate_request_body|HTTP methods when generate requestBody|`[post put patch]`|
|
101
|
+
|ignored_http_statuses_when_generate_component_schema|Ignore HTTP statuses when generate component schema|`[204 404]`|
|
102
|
+
|namespace_type|namespace for components(schemas/requestBodies) name| `underbar` |
|
103
|
+
|deploy_dir_path|deploy directory.|`"./deploy_docs"`|
|
104
|
+
|
105
|
+
#### server
|
106
|
+
|
107
|
+
|option|children option|description|default|
|
108
|
+
|------|---------------|-----------|-------|
|
109
|
+
|server|data|Server data (url, description) |[{ url: `http://localhost:3000`, description: `localhost` }] |
|
110
|
+
|
111
|
+
#### swagger
|
112
|
+
|
113
|
+
|option|children option|grandchild option|description|default|
|
114
|
+
|------|---------------|-----------------|-----------|-------|
|
115
|
+
|swagger|ui|image|Swagger UI Docker Image|`"swaggerapi/swagger-ui"`|
|
116
|
+
|swagger|ui|port|Swagger UI Port|`"8080"`|
|
117
|
+
|swagger|ui|exposed_port|Swagger UI Exposed Port|`"8080/tcp"`|
|
118
|
+
|swagger|ui|volume|Swagger UI Volume|`"/app/swagger.json"`|
|
119
|
+
|swagger|editor|image|Swagger Editor Docker Image|`"swaggerapi/swagger-editor"`|
|
120
|
+
|swagger|editor|port|Swagger Editor Port|`"8080"`|
|
121
|
+
|swagger|editor|exposed_port|Swagger Editor Exposed Port|`"8080/tcp"`|
|
122
|
+
|
123
|
+
#### hook
|
124
|
+
|
125
|
+
|option|description|default|
|
126
|
+
|------|-----------|-------|
|
127
|
+
|use_object_classes|Object class(hook class) to generate Openapi document|{ info_object: `R2OAS::Schema::V3::InfoObject`,<br>paths_object: `R2OAS::Schema::V3::PathsObject`,<br>path_item_object: `R2OAS::Schema::V3::PathItemObject`, external_document_object: `R2OAS::Schema::V3::ExternalDocumentObject`,<br> components_object: `R2OAS::Schema::V3::ComponentsObject`,<br> components_schema_object: `R2OAS::Schema::V3::Components::SchemaObject`, <br> components_request_body_object:`R2OAS::Schema::V3::Components::RequestBodyObject` }|
|
128
|
+
|
129
|
+
#### tool
|
130
|
+
|
131
|
+
|option|children option|grandchild option|description|default|
|
132
|
+
|------|---------------|-----------------|-----------|-------|
|
133
|
+
|tool|paths_stats|month_to_turn_to_warning_color|Elapsed month to issue a warning|`3`|
|
134
|
+
|tool|paths_stats|warning_color|Warning Color|`:red`|
|
135
|
+
|tool|paths_stats|table_title_color|Table Title Color|`:yellow`|
|
136
|
+
|tool|paths_stats|heading_color|Heading Color|`:yellow`|
|
137
|
+
|tool|paths_stats|highlight_color|Highlight Color|`:magenta`|
|
138
|
+
|
139
|
+
Please refer to [here](https://github.com/janlelis/paint) for the color.
|
140
|
+
|
141
|
+
## Environment variables
|
142
|
+
|
143
|
+
We explain the environment variables that can be set.
|
144
|
+
|
145
|
+
|variable|description|default|
|
146
|
+
|--------|-----------|-------|
|
147
|
+
|PATHS_FILE|Specify one paths file path|`""`|
|
148
|
+
|OAS_FILE|Specify swagger file path to analyze|`""`|
|
149
|
+
|
150
|
+
|
151
|
+
## .paths
|
152
|
+
|
153
|
+
Writing file paths in .paths will only read them.
|
154
|
+
You can comment out with `#`
|
155
|
+
|
156
|
+
`oas_docs/.paths`
|
157
|
+
|
158
|
+
```
|
159
|
+
#account_user_role.yml # ignore
|
160
|
+
account.yml
|
161
|
+
account.yml # ignore
|
162
|
+
account.yml # ignore
|
163
|
+
```
|