jdoc 0.4.2 → 0.4.4
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 +5 -5
- data/.github/release.yml +23 -0
- data/.github/workflows/bump-request.yml +26 -0
- data/.github/workflows/ci.yml +25 -0
- data/.github/workflows/github-label-sync.yml +18 -0
- data/.github/workflows/release.yml +14 -0
- data/.gitignore +0 -1
- data/CHANGELOG.md +33 -0
- data/Gemfile.lock +74 -0
- data/README.md +4 -1
- data/Rakefile +4 -0
- data/bin/jdoc +24 -2
- data/example-api-documentation.html +364 -0
- data/jdoc.gemspec +2 -2
- data/lib/jdoc/generator.rb +2 -2
- data/lib/jdoc/link.rb +2 -2
- data/lib/jdoc/version.rb +1 -1
- data/spec/jdoc/generator_spec.rb +10 -0
- data/spec/spec_helper.rb +0 -1
- metadata +14 -9
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 2985c00f49d908beecf1c19950d19936e6e2cda00d3e252523b5f6c084471c34
|
|
4
|
+
data.tar.gz: 21cfc1d002fbe5daa43cb72d663fd32f963dfb9538dcabbea251607681b9ef5c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 06ab1757a35ecb7f108cfdcc0d9a67f5c2692bd2b39951bab5b8246c3e65f954f4bf745f35130d5272097cf29f9114ea80f349fad48c48dbe4a8b1a65051158b
|
|
7
|
+
data.tar.gz: afdf9f5a2f4d24a88948b6eafe8910b12283f0f9df385bca89adeb8263f301dad3bafb97bd0621b63b6827fc1549eb0feebff44c2b678dabb9b4f1ef860e4b38
|
data/.github/release.yml
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
changelog:
|
|
2
|
+
categories:
|
|
3
|
+
- title: Added
|
|
4
|
+
labels:
|
|
5
|
+
- add
|
|
6
|
+
- title: Changed
|
|
7
|
+
labels:
|
|
8
|
+
- change
|
|
9
|
+
- title: Deprecated
|
|
10
|
+
labels:
|
|
11
|
+
- deprecate
|
|
12
|
+
- title: Fixed
|
|
13
|
+
labels:
|
|
14
|
+
- fix
|
|
15
|
+
- title: Removed
|
|
16
|
+
labels:
|
|
17
|
+
- remove
|
|
18
|
+
- title: Security
|
|
19
|
+
labels:
|
|
20
|
+
- security
|
|
21
|
+
- title: Others
|
|
22
|
+
labels:
|
|
23
|
+
- "*"
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
name: bump-request
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_dispatch:
|
|
5
|
+
inputs:
|
|
6
|
+
version:
|
|
7
|
+
description: Version to change to.
|
|
8
|
+
required: true
|
|
9
|
+
type: string
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
run:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v3
|
|
16
|
+
- name: Set up Ruby
|
|
17
|
+
uses: ruby/setup-ruby@v1
|
|
18
|
+
with:
|
|
19
|
+
ruby-version: '3.3'
|
|
20
|
+
bundler-cache: true
|
|
21
|
+
- uses: r7kamura/bump-request@v0
|
|
22
|
+
with:
|
|
23
|
+
command: |
|
|
24
|
+
sed -i -r 's/([0-9]+\.[0-9]+\.[0-9]+)/${{ inputs.version }}/' lib/*/version.rb
|
|
25
|
+
bundle install
|
|
26
|
+
version: ${{ inputs.version }}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- master
|
|
7
|
+
pull_request:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
rspec:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
name: Ruby ${{ matrix.ruby }}
|
|
13
|
+
strategy:
|
|
14
|
+
matrix:
|
|
15
|
+
ruby:
|
|
16
|
+
- '3.3'
|
|
17
|
+
steps:
|
|
18
|
+
- uses: actions/checkout@v3
|
|
19
|
+
- name: Set up Ruby
|
|
20
|
+
uses: ruby/setup-ruby@v1
|
|
21
|
+
with:
|
|
22
|
+
ruby-version: ${{ matrix.ruby }}
|
|
23
|
+
bundler-cache: true
|
|
24
|
+
- name: Run the default task
|
|
25
|
+
run: bundle exec rake
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
name: github-label-sync
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- master
|
|
7
|
+
paths:
|
|
8
|
+
- .github/workflows/github-label-sync.yml
|
|
9
|
+
workflow_dispatch:
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
build:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: r7kamura/github-label-sync-action@v0
|
|
16
|
+
with:
|
|
17
|
+
source_path: labels-keepachangelog.yml
|
|
18
|
+
source_repository: r7kamura/github-label-presets
|
data/.gitignore
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -1,90 +1,123 @@
|
|
|
1
|
+
## 0.4.3
|
|
2
|
+
|
|
3
|
+
- Add some CLI options (Thx @k1LoW)
|
|
4
|
+
|
|
1
5
|
## 0.4.2
|
|
6
|
+
|
|
2
7
|
- Show reason phrase in response example (Thx @minodisk)
|
|
3
8
|
|
|
4
9
|
## 0.4.1
|
|
10
|
+
|
|
5
11
|
- Use 204 for `mediaType: "null"`
|
|
6
12
|
|
|
7
13
|
## 0.4.0
|
|
14
|
+
|
|
8
15
|
- Recognize `mediaType: 'null'` as "No response body"
|
|
9
16
|
|
|
10
17
|
## 0.3.4
|
|
18
|
+
|
|
11
19
|
- Treat empty request parameters as no request body
|
|
12
20
|
|
|
13
21
|
## 0.3.3
|
|
22
|
+
|
|
14
23
|
- Improve pattern format in properties section
|
|
15
24
|
|
|
16
25
|
## 0.3.2
|
|
26
|
+
|
|
17
27
|
- Add generator options to change template
|
|
18
28
|
- Add request parameters for each endpoint
|
|
19
29
|
|
|
20
30
|
## 0.3.1
|
|
31
|
+
|
|
21
32
|
- Add error handling for ExampleNotFound
|
|
22
33
|
|
|
23
34
|
## 0.3.0
|
|
35
|
+
|
|
24
36
|
- Change example response status and body to PUT & DELETE requests
|
|
25
37
|
- Improve request path example by resolving variable in path
|
|
26
38
|
|
|
27
39
|
## 0.2.1
|
|
40
|
+
|
|
28
41
|
- Support multipart/form-data
|
|
29
42
|
|
|
30
43
|
## 0.2.0
|
|
44
|
+
|
|
31
45
|
- Show schema description on docs if exists
|
|
32
46
|
|
|
33
47
|
## 0.1.9
|
|
48
|
+
|
|
34
49
|
- Support property that has no type
|
|
35
50
|
|
|
36
51
|
## 0.1.8
|
|
52
|
+
|
|
37
53
|
- Support property that is an array of primitive values
|
|
38
54
|
|
|
39
55
|
## 0.1.7
|
|
56
|
+
|
|
40
57
|
- Support query string example in GET request
|
|
41
58
|
- Improve the description property visibility
|
|
42
59
|
|
|
43
60
|
## 0.1.6
|
|
61
|
+
|
|
44
62
|
- Disable `<em>` feature of Redcarpet
|
|
45
63
|
|
|
46
64
|
## 0.1.5
|
|
65
|
+
|
|
47
66
|
- Fix ToC link on HTML docs
|
|
48
67
|
|
|
49
68
|
## 0.1.4
|
|
69
|
+
|
|
50
70
|
- Provide :html option to render docs in HTML
|
|
51
71
|
|
|
52
72
|
## 0.1.3
|
|
73
|
+
|
|
53
74
|
- Use its pointer name if a resource has no title property
|
|
54
75
|
|
|
55
76
|
## 0.1.2
|
|
77
|
+
|
|
56
78
|
- Use .schema property for request body if exists
|
|
57
79
|
- Improve array resource handling
|
|
58
80
|
|
|
59
81
|
## 0.1.1
|
|
82
|
+
|
|
60
83
|
- Support has-one relation
|
|
61
84
|
|
|
62
85
|
## 0.1.0
|
|
86
|
+
|
|
63
87
|
- Show resources which have no links
|
|
64
88
|
|
|
65
89
|
## 0.0.9
|
|
90
|
+
|
|
66
91
|
- Support array property
|
|
67
92
|
|
|
68
93
|
## 0.0.8
|
|
94
|
+
|
|
69
95
|
- Fix resource equality
|
|
70
96
|
|
|
71
97
|
## 0.0.7
|
|
98
|
+
|
|
72
99
|
- Support `false` & `null` example value
|
|
73
100
|
|
|
74
101
|
## 0.0.6
|
|
102
|
+
|
|
75
103
|
- Use root API endpoint at example response
|
|
76
104
|
|
|
77
105
|
## 0.0.5
|
|
106
|
+
|
|
78
107
|
- Remove dependency on multi_json
|
|
79
108
|
|
|
80
109
|
## 0.0.4
|
|
110
|
+
|
|
81
111
|
- Support whitespace and multiple templates in href
|
|
82
112
|
|
|
83
113
|
## 0.0.3
|
|
114
|
+
|
|
84
115
|
- Fix missing gem dependencies
|
|
85
116
|
|
|
86
117
|
## 0.0.2
|
|
118
|
+
|
|
87
119
|
- Remove dependency on rack-spec
|
|
88
120
|
|
|
89
121
|
## 0.0.1
|
|
122
|
+
|
|
90
123
|
- 1st Release
|
data/Gemfile.lock
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
PATH
|
|
2
|
+
remote: .
|
|
3
|
+
specs:
|
|
4
|
+
jdoc (0.4.4)
|
|
5
|
+
activesupport
|
|
6
|
+
erubis
|
|
7
|
+
json_schema
|
|
8
|
+
rack
|
|
9
|
+
redcarpet
|
|
10
|
+
|
|
11
|
+
GEM
|
|
12
|
+
remote: https://rubygems.org/
|
|
13
|
+
specs:
|
|
14
|
+
activesupport (7.1.2)
|
|
15
|
+
base64
|
|
16
|
+
bigdecimal
|
|
17
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
|
18
|
+
connection_pool (>= 2.2.5)
|
|
19
|
+
drb
|
|
20
|
+
i18n (>= 1.6, < 2)
|
|
21
|
+
minitest (>= 5.1)
|
|
22
|
+
mutex_m
|
|
23
|
+
tzinfo (~> 2.0)
|
|
24
|
+
base64 (0.2.0)
|
|
25
|
+
bigdecimal (3.1.5)
|
|
26
|
+
coderay (1.1.3)
|
|
27
|
+
concurrent-ruby (1.2.2)
|
|
28
|
+
connection_pool (2.4.1)
|
|
29
|
+
diff-lcs (1.5.0)
|
|
30
|
+
drb (2.2.0)
|
|
31
|
+
ruby2_keywords
|
|
32
|
+
erubis (2.7.0)
|
|
33
|
+
i18n (1.14.1)
|
|
34
|
+
concurrent-ruby (~> 1.0)
|
|
35
|
+
json_schema (0.21.0)
|
|
36
|
+
method_source (1.0.0)
|
|
37
|
+
minitest (5.21.1)
|
|
38
|
+
mutex_m (0.2.0)
|
|
39
|
+
pry (0.14.2)
|
|
40
|
+
coderay (~> 1.1)
|
|
41
|
+
method_source (~> 1.0)
|
|
42
|
+
rack (3.0.8)
|
|
43
|
+
rake (13.1.0)
|
|
44
|
+
redcarpet (3.6.0)
|
|
45
|
+
rspec (3.12.0)
|
|
46
|
+
rspec-core (~> 3.12.0)
|
|
47
|
+
rspec-expectations (~> 3.12.0)
|
|
48
|
+
rspec-mocks (~> 3.12.0)
|
|
49
|
+
rspec-core (3.12.2)
|
|
50
|
+
rspec-support (~> 3.12.0)
|
|
51
|
+
rspec-expectations (3.12.3)
|
|
52
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
53
|
+
rspec-support (~> 3.12.0)
|
|
54
|
+
rspec-mocks (3.12.6)
|
|
55
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
56
|
+
rspec-support (~> 3.12.0)
|
|
57
|
+
rspec-support (3.12.1)
|
|
58
|
+
ruby2_keywords (0.0.5)
|
|
59
|
+
tzinfo (2.0.6)
|
|
60
|
+
concurrent-ruby (~> 1.0)
|
|
61
|
+
|
|
62
|
+
PLATFORMS
|
|
63
|
+
ruby
|
|
64
|
+
x86_64-linux
|
|
65
|
+
|
|
66
|
+
DEPENDENCIES
|
|
67
|
+
bundler (>= 1.6)
|
|
68
|
+
jdoc!
|
|
69
|
+
pry
|
|
70
|
+
rake
|
|
71
|
+
rspec (>= 2.14.1)
|
|
72
|
+
|
|
73
|
+
BUNDLED WITH
|
|
74
|
+
2.5.3
|
data/README.md
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
# Jdoc
|
|
2
|
+
|
|
3
|
+
[](https://github.com/r7kamura/jdoc/actions/workflows/ci.yml)
|
|
4
|
+
|
|
2
5
|
Generate API documentation from JSON Schema.
|
|
3
6
|
|
|
4
7
|
## Install
|
|
@@ -10,5 +13,5 @@ $ gem install jdoc
|
|
|
10
13
|
See [example-api-documentation.md](example-api-documentation.md) generated by the following command.
|
|
11
14
|
|
|
12
15
|
```sh
|
|
13
|
-
$ jdoc spec/fixtures/schema.
|
|
16
|
+
$ jdoc spec/fixtures/schema.yml > example-api-documentation.md
|
|
14
17
|
```
|
data/Rakefile
CHANGED
data/bin/jdoc
CHANGED
|
@@ -2,9 +2,26 @@
|
|
|
2
2
|
$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
|
|
3
3
|
require "jdoc"
|
|
4
4
|
require "yaml"
|
|
5
|
+
require "optparse"
|
|
6
|
+
|
|
7
|
+
opt = OptionParser.new
|
|
8
|
+
banner = 'Usage: jdoc <schema.json or schema.yml> [options]'
|
|
9
|
+
opt.banner = banner
|
|
10
|
+
Version = Jdoc::VERSION
|
|
11
|
+
options = {
|
|
12
|
+
html: false,
|
|
13
|
+
html_template_path: nil,
|
|
14
|
+
markdown_template_path: nil
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
opt.on("--html") { |_| options[:html] = true }
|
|
18
|
+
opt.on("--html-template-path ERB_FILE") { |v| options[:html_template_path] = v }
|
|
19
|
+
opt.on("--markdown-template-path ERB_FILE") { |v| options[:markdown_template_path] = v }
|
|
20
|
+
|
|
21
|
+
opt.parse!(ARGV)
|
|
5
22
|
|
|
6
23
|
unless path = ARGV[0]
|
|
7
|
-
puts
|
|
24
|
+
puts banner
|
|
8
25
|
exit
|
|
9
26
|
end
|
|
10
27
|
|
|
@@ -16,4 +33,9 @@ else
|
|
|
16
33
|
schema = JSON.parse(str)
|
|
17
34
|
end
|
|
18
35
|
|
|
19
|
-
puts Jdoc::Generator.call(
|
|
36
|
+
puts Jdoc::Generator.call(
|
|
37
|
+
schema,
|
|
38
|
+
html: options[:html],
|
|
39
|
+
html_template_path: options[:html_template_path],
|
|
40
|
+
markdown_template_path: options[:markdown_template_path],
|
|
41
|
+
)
|
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
<!DOCTYPE HTML>
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<title>API Docs</title>
|
|
6
|
+
<style>
|
|
7
|
+
body {
|
|
8
|
+
width: 920px;
|
|
9
|
+
margin: 0 auto;
|
|
10
|
+
font-size: 14px;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
a {
|
|
14
|
+
color: #4183C4;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
pre {
|
|
18
|
+
color: #393939;
|
|
19
|
+
background-color: #fafafb;
|
|
20
|
+
padding: 10px;
|
|
21
|
+
margin: 2em 0;
|
|
22
|
+
border: 1px solid #cacaca;
|
|
23
|
+
border-radius: 3px;
|
|
24
|
+
font: 12px/1.4em Consolas, 'Liberation Mono', Courier, monospace;
|
|
25
|
+
overflow: auto;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
ol code,
|
|
29
|
+
ul code,
|
|
30
|
+
p code {
|
|
31
|
+
font-size: 12px;
|
|
32
|
+
margin: 0;
|
|
33
|
+
border: 1px solid #ddd;
|
|
34
|
+
background-color: #f8f8f8;
|
|
35
|
+
border-radius: 3px;
|
|
36
|
+
padding: 0;
|
|
37
|
+
}
|
|
38
|
+
</style>
|
|
39
|
+
</head>
|
|
40
|
+
<body>
|
|
41
|
+
<h1 id="example-api">Example API</h1>
|
|
42
|
+
|
|
43
|
+
<p>A schema for a small example API.</p>
|
|
44
|
+
|
|
45
|
+
<ul>
|
|
46
|
+
<li><a href="#app">App</a>
|
|
47
|
+
|
|
48
|
+
<ul>
|
|
49
|
+
<li><a href="#post-apps">POST /apps</a></li>
|
|
50
|
+
<li><a href="#delete-appsid">DELETE /apps/:id</a></li>
|
|
51
|
+
<li><a href="#get-appsid">GET /apps/:id</a></li>
|
|
52
|
+
<li><a href="#get-apps">GET /apps</a></li>
|
|
53
|
+
<li><a href="#patch-appsid">PATCH /apps/:id</a></li>
|
|
54
|
+
<li><a href="#post-appsidfiles">POST /apps/:id/files</a></li>
|
|
55
|
+
</ul></li>
|
|
56
|
+
<li><a href="#recipe">Recipe</a>
|
|
57
|
+
|
|
58
|
+
<ul>
|
|
59
|
+
<li><a href="#get-recipes">GET /recipes</a></li>
|
|
60
|
+
</ul></li>
|
|
61
|
+
<li><a href="#user">User</a></li>
|
|
62
|
+
</ul>
|
|
63
|
+
|
|
64
|
+
<h2 id="app">App</h2>
|
|
65
|
+
|
|
66
|
+
<p>An app is a program to be deployed.</p>
|
|
67
|
+
|
|
68
|
+
<h3 id="properties">Properties</h3>
|
|
69
|
+
|
|
70
|
+
<ul>
|
|
71
|
+
<li>id
|
|
72
|
+
|
|
73
|
+
<ul>
|
|
74
|
+
<li>unique identifier of app</li>
|
|
75
|
+
<li>Example: <code>"01234567-89ab-cdef-0123-456789abcdef"</code></li>
|
|
76
|
+
<li>Type: string</li>
|
|
77
|
+
<li>Format: uuid</li>
|
|
78
|
+
<li>ReadOnly: true</li>
|
|
79
|
+
</ul></li>
|
|
80
|
+
<li>name
|
|
81
|
+
|
|
82
|
+
<ul>
|
|
83
|
+
<li>unique name of app</li>
|
|
84
|
+
<li>Example: <code>"example"</code></li>
|
|
85
|
+
<li>Type: string</li>
|
|
86
|
+
<li>Pattern: <code>/^[a-z][a-z0-9-]{3,50}$/</code></li>
|
|
87
|
+
</ul></li>
|
|
88
|
+
<li>private
|
|
89
|
+
|
|
90
|
+
<ul>
|
|
91
|
+
<li>true if this resource is private use</li>
|
|
92
|
+
<li>Example: <code>false</code></li>
|
|
93
|
+
<li>Type: boolean</li>
|
|
94
|
+
</ul></li>
|
|
95
|
+
<li>deleted_at
|
|
96
|
+
|
|
97
|
+
<ul>
|
|
98
|
+
<li>When this resource was deleted at</li>
|
|
99
|
+
<li>Example: <code>nil</code></li>
|
|
100
|
+
<li>Type: null</li>
|
|
101
|
+
</ul></li>
|
|
102
|
+
<li>user_ids
|
|
103
|
+
|
|
104
|
+
<ul>
|
|
105
|
+
<li>Type: array</li>
|
|
106
|
+
</ul></li>
|
|
107
|
+
<li>users
|
|
108
|
+
|
|
109
|
+
<ul>
|
|
110
|
+
<li>Type: array</li>
|
|
111
|
+
</ul></li>
|
|
112
|
+
</ul>
|
|
113
|
+
|
|
114
|
+
<h3 id="post-apps">POST /apps</h3>
|
|
115
|
+
|
|
116
|
+
<p>Create a new app.</p>
|
|
117
|
+
|
|
118
|
+
<ul>
|
|
119
|
+
<li>name
|
|
120
|
+
|
|
121
|
+
<ul>
|
|
122
|
+
<li>unique name of app</li>
|
|
123
|
+
<li>Example: <code>"example"</code></li>
|
|
124
|
+
<li>Type: string</li>
|
|
125
|
+
<li>Pattern: <code>/^[a-z][a-z0-9-]{3,50}$/</code></li>
|
|
126
|
+
</ul></li>
|
|
127
|
+
</ul>
|
|
128
|
+
|
|
129
|
+
<pre><code>POST /apps HTTP/1.1
|
|
130
|
+
Content-Type: application/json
|
|
131
|
+
Host: api.example.com
|
|
132
|
+
|
|
133
|
+
{
|
|
134
|
+
"name": "example"
|
|
135
|
+
}
|
|
136
|
+
</code></pre>
|
|
137
|
+
|
|
138
|
+
<pre><code>HTTP/1.1 201 Created
|
|
139
|
+
Content-Type: application/json
|
|
140
|
+
|
|
141
|
+
{
|
|
142
|
+
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
|
143
|
+
"name": "example",
|
|
144
|
+
"private": false,
|
|
145
|
+
"deleted_at": null,
|
|
146
|
+
"user_ids": [
|
|
147
|
+
1
|
|
148
|
+
],
|
|
149
|
+
"users": [
|
|
150
|
+
{
|
|
151
|
+
"name": "alice"
|
|
152
|
+
}
|
|
153
|
+
]
|
|
154
|
+
}
|
|
155
|
+
</code></pre>
|
|
156
|
+
|
|
157
|
+
<h3 id="delete-apps-id">DELETE /apps/:id</h3>
|
|
158
|
+
|
|
159
|
+
<p>Delete an existing app.</p>
|
|
160
|
+
|
|
161
|
+
<pre><code>DELETE /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
|
|
162
|
+
Host: api.example.com
|
|
163
|
+
</code></pre>
|
|
164
|
+
|
|
165
|
+
<pre><code>HTTP/1.1 204 No Content
|
|
166
|
+
</code></pre>
|
|
167
|
+
|
|
168
|
+
<h3 id="get-apps-id">GET /apps/:id</h3>
|
|
169
|
+
|
|
170
|
+
<p>Info for existing app.</p>
|
|
171
|
+
|
|
172
|
+
<pre><code>GET /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
|
|
173
|
+
Host: api.example.com
|
|
174
|
+
</code></pre>
|
|
175
|
+
|
|
176
|
+
<pre><code>HTTP/1.1 200 OK
|
|
177
|
+
Content-Type: application/json
|
|
178
|
+
|
|
179
|
+
{
|
|
180
|
+
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
|
181
|
+
"name": "example",
|
|
182
|
+
"private": false,
|
|
183
|
+
"deleted_at": null,
|
|
184
|
+
"user_ids": [
|
|
185
|
+
1
|
|
186
|
+
],
|
|
187
|
+
"users": [
|
|
188
|
+
{
|
|
189
|
+
"name": "alice"
|
|
190
|
+
}
|
|
191
|
+
]
|
|
192
|
+
}
|
|
193
|
+
</code></pre>
|
|
194
|
+
|
|
195
|
+
<h3 id="get-apps">GET /apps</h3>
|
|
196
|
+
|
|
197
|
+
<p>List existing apps.</p>
|
|
198
|
+
|
|
199
|
+
<pre><code>GET /apps HTTP/1.1
|
|
200
|
+
Host: api.example.com
|
|
201
|
+
</code></pre>
|
|
202
|
+
|
|
203
|
+
<pre><code>HTTP/1.1 200 OK
|
|
204
|
+
Content-Type: application/json
|
|
205
|
+
|
|
206
|
+
[
|
|
207
|
+
{
|
|
208
|
+
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
|
209
|
+
"name": "example",
|
|
210
|
+
"private": false,
|
|
211
|
+
"deleted_at": null,
|
|
212
|
+
"user_ids": [
|
|
213
|
+
1
|
|
214
|
+
],
|
|
215
|
+
"users": [
|
|
216
|
+
{
|
|
217
|
+
"name": "alice"
|
|
218
|
+
}
|
|
219
|
+
]
|
|
220
|
+
}
|
|
221
|
+
]
|
|
222
|
+
</code></pre>
|
|
223
|
+
|
|
224
|
+
<h3 id="patch-apps-id">PATCH /apps/:id</h3>
|
|
225
|
+
|
|
226
|
+
<p>Update an existing app.</p>
|
|
227
|
+
|
|
228
|
+
<ul>
|
|
229
|
+
<li>name
|
|
230
|
+
|
|
231
|
+
<ul>
|
|
232
|
+
<li>unique name of app</li>
|
|
233
|
+
<li>Example: <code>"example"</code></li>
|
|
234
|
+
<li>Type: string</li>
|
|
235
|
+
<li>Pattern: <code>/^[a-z][a-z0-9-]{3,50}$/</code></li>
|
|
236
|
+
</ul></li>
|
|
237
|
+
</ul>
|
|
238
|
+
|
|
239
|
+
<pre><code>PATCH /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
|
|
240
|
+
Content-Type: application/json
|
|
241
|
+
Host: api.example.com
|
|
242
|
+
|
|
243
|
+
{
|
|
244
|
+
"name": "example"
|
|
245
|
+
}
|
|
246
|
+
</code></pre>
|
|
247
|
+
|
|
248
|
+
<pre><code>HTTP/1.1 200 OK
|
|
249
|
+
Content-Type: application/json
|
|
250
|
+
|
|
251
|
+
{
|
|
252
|
+
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
|
253
|
+
"name": "example",
|
|
254
|
+
"private": false,
|
|
255
|
+
"deleted_at": null,
|
|
256
|
+
"user_ids": [
|
|
257
|
+
1
|
|
258
|
+
],
|
|
259
|
+
"users": [
|
|
260
|
+
{
|
|
261
|
+
"name": "alice"
|
|
262
|
+
}
|
|
263
|
+
]
|
|
264
|
+
}
|
|
265
|
+
</code></pre>
|
|
266
|
+
|
|
267
|
+
<h3 id="post-apps-id-files">POST /apps/:id/files</h3>
|
|
268
|
+
|
|
269
|
+
<p>Upload an attachment file for an app</p>
|
|
270
|
+
|
|
271
|
+
<ul>
|
|
272
|
+
<li>file
|
|
273
|
+
|
|
274
|
+
<ul>
|
|
275
|
+
<li>an attachment of app</li>
|
|
276
|
+
<li>Example: <code>"... contents of file ..."</code></li>
|
|
277
|
+
<li>Type: string</li>
|
|
278
|
+
</ul></li>
|
|
279
|
+
</ul>
|
|
280
|
+
|
|
281
|
+
<pre><code>POST /apps/01234567-89ab-cdef-0123-456789abcdef/files HTTP/1.1
|
|
282
|
+
Content-Type: multipart/form-data; boundary=---BoundaryX
|
|
283
|
+
Host: api.example.com
|
|
284
|
+
|
|
285
|
+
-----BoundaryX
|
|
286
|
+
Content-Disposition: form-data; name="[file]"
|
|
287
|
+
|
|
288
|
+
... contents of file ...
|
|
289
|
+
|
|
290
|
+
-----BoundaryX--
|
|
291
|
+
</code></pre>
|
|
292
|
+
|
|
293
|
+
<pre><code>HTTP/1.1 201 Created
|
|
294
|
+
Content-Type: application/json
|
|
295
|
+
|
|
296
|
+
{
|
|
297
|
+
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
|
298
|
+
"name": "example",
|
|
299
|
+
"private": false,
|
|
300
|
+
"deleted_at": null,
|
|
301
|
+
"user_ids": [
|
|
302
|
+
1
|
|
303
|
+
],
|
|
304
|
+
"users": [
|
|
305
|
+
{
|
|
306
|
+
"name": "alice"
|
|
307
|
+
}
|
|
308
|
+
]
|
|
309
|
+
}
|
|
310
|
+
</code></pre>
|
|
311
|
+
|
|
312
|
+
<h2 id="recipe">Recipe</h2>
|
|
313
|
+
|
|
314
|
+
<h3 id="properties">Properties</h3>
|
|
315
|
+
|
|
316
|
+
<ul>
|
|
317
|
+
<li>name
|
|
318
|
+
|
|
319
|
+
<ul>
|
|
320
|
+
<li>Example: <code>"Sushi"</code></li>
|
|
321
|
+
</ul></li>
|
|
322
|
+
<li>user
|
|
323
|
+
|
|
324
|
+
<ul>
|
|
325
|
+
<li>Type: object</li>
|
|
326
|
+
</ul></li>
|
|
327
|
+
</ul>
|
|
328
|
+
|
|
329
|
+
<h3 id="get-recipes">GET /recipes</h3>
|
|
330
|
+
|
|
331
|
+
<p>List recipes</p>
|
|
332
|
+
|
|
333
|
+
<pre><code>GET /recipes HTTP/1.1
|
|
334
|
+
Host: api.example.com
|
|
335
|
+
</code></pre>
|
|
336
|
+
|
|
337
|
+
<pre><code>HTTP/1.1 200 OK
|
|
338
|
+
Content-Type: application/json
|
|
339
|
+
|
|
340
|
+
[
|
|
341
|
+
{
|
|
342
|
+
"name": "Sushi",
|
|
343
|
+
"user": {
|
|
344
|
+
"name": "alice"
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
]
|
|
348
|
+
</code></pre>
|
|
349
|
+
|
|
350
|
+
<h2 id="user">User</h2>
|
|
351
|
+
|
|
352
|
+
<h3 id="properties">Properties</h3>
|
|
353
|
+
|
|
354
|
+
<ul>
|
|
355
|
+
<li>name
|
|
356
|
+
|
|
357
|
+
<ul>
|
|
358
|
+
<li>Example: <code>"alice"</code></li>
|
|
359
|
+
<li>Type: string</li>
|
|
360
|
+
</ul></li>
|
|
361
|
+
</ul>
|
|
362
|
+
|
|
363
|
+
</body>
|
|
364
|
+
</html>
|
data/jdoc.gemspec
CHANGED
|
@@ -21,8 +21,8 @@ Gem::Specification.new do |spec|
|
|
|
21
21
|
spec.add_dependency "json_schema"
|
|
22
22
|
spec.add_dependency "rack"
|
|
23
23
|
spec.add_dependency "redcarpet"
|
|
24
|
-
spec.add_development_dependency "bundler", "
|
|
24
|
+
spec.add_development_dependency "bundler", ">= 1.6"
|
|
25
25
|
spec.add_development_dependency "pry"
|
|
26
26
|
spec.add_development_dependency "rake"
|
|
27
|
-
spec.add_development_dependency "rspec", "2.14.1"
|
|
27
|
+
spec.add_development_dependency "rspec", ">= 2.14.1"
|
|
28
28
|
end
|
data/lib/jdoc/generator.rb
CHANGED
data/lib/jdoc/link.rb
CHANGED
|
@@ -55,7 +55,7 @@ module Jdoc
|
|
|
55
55
|
# @return [String] Request path name, defined at href property
|
|
56
56
|
# @note URI Template is replaced with placeholder
|
|
57
57
|
# @example
|
|
58
|
-
# link.path #=> "
|
|
58
|
+
# link.path #=> "/apps/:id"
|
|
59
59
|
def path
|
|
60
60
|
@path ||= @raw_link.href.gsub(/{(.+?)}/) do
|
|
61
61
|
":" + CGI.unescape($1).gsub(/[()\s]/, "").split("/").last
|
|
@@ -65,7 +65,7 @@ module Jdoc
|
|
|
65
65
|
# @returns [String] Path with embedded example variable
|
|
66
66
|
# @raise [Rack::Spec::Mock::ExampleNotFound]
|
|
67
67
|
# @example
|
|
68
|
-
# link.example_path #=> "
|
|
68
|
+
# link.example_path #=> "/apps/1"
|
|
69
69
|
def example_path
|
|
70
70
|
@example_path ||= @raw_link.href.gsub(/{\((.+?)\)}/) do
|
|
71
71
|
pointer = CGI.unescape($1)
|
data/lib/jdoc/version.rb
CHANGED
data/spec/jdoc/generator_spec.rb
CHANGED
|
@@ -19,5 +19,15 @@ describe Jdoc::Generator do
|
|
|
19
19
|
it "returns a String of API documentation in Markdown from given JSON Schema" do
|
|
20
20
|
should == File.read(File.expand_path("../../../example-api-documentation.md", __FILE__))
|
|
21
21
|
end
|
|
22
|
+
|
|
23
|
+
context "with html: true" do
|
|
24
|
+
subject do
|
|
25
|
+
described_class.call(schema, html: true)
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
it "returns a String of API documentation in HTML from given JSON Schema" do
|
|
29
|
+
should == File.read(File.expand_path("../../../example-api-documentation.html", __FILE__))
|
|
30
|
+
end
|
|
31
|
+
end
|
|
22
32
|
end
|
|
23
33
|
end
|
data/spec/spec_helper.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: jdoc
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.4.
|
|
4
|
+
version: 0.4.4
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Ryo Nakamura
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date:
|
|
11
|
+
date: 2024-01-15 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: activesupport
|
|
@@ -84,14 +84,14 @@ dependencies:
|
|
|
84
84
|
name: bundler
|
|
85
85
|
requirement: !ruby/object:Gem::Requirement
|
|
86
86
|
requirements:
|
|
87
|
-
- - "
|
|
87
|
+
- - ">="
|
|
88
88
|
- !ruby/object:Gem::Version
|
|
89
89
|
version: '1.6'
|
|
90
90
|
type: :development
|
|
91
91
|
prerelease: false
|
|
92
92
|
version_requirements: !ruby/object:Gem::Requirement
|
|
93
93
|
requirements:
|
|
94
|
-
- - "
|
|
94
|
+
- - ">="
|
|
95
95
|
- !ruby/object:Gem::Version
|
|
96
96
|
version: '1.6'
|
|
97
97
|
- !ruby/object:Gem::Dependency
|
|
@@ -126,14 +126,14 @@ dependencies:
|
|
|
126
126
|
name: rspec
|
|
127
127
|
requirement: !ruby/object:Gem::Requirement
|
|
128
128
|
requirements:
|
|
129
|
-
- -
|
|
129
|
+
- - ">="
|
|
130
130
|
- !ruby/object:Gem::Version
|
|
131
131
|
version: 2.14.1
|
|
132
132
|
type: :development
|
|
133
133
|
prerelease: false
|
|
134
134
|
version_requirements: !ruby/object:Gem::Requirement
|
|
135
135
|
requirements:
|
|
136
|
-
- -
|
|
136
|
+
- - ">="
|
|
137
137
|
- !ruby/object:Gem::Version
|
|
138
138
|
version: 2.14.1
|
|
139
139
|
description:
|
|
@@ -144,13 +144,20 @@ executables:
|
|
|
144
144
|
extensions: []
|
|
145
145
|
extra_rdoc_files: []
|
|
146
146
|
files:
|
|
147
|
+
- ".github/release.yml"
|
|
148
|
+
- ".github/workflows/bump-request.yml"
|
|
149
|
+
- ".github/workflows/ci.yml"
|
|
150
|
+
- ".github/workflows/github-label-sync.yml"
|
|
151
|
+
- ".github/workflows/release.yml"
|
|
147
152
|
- ".gitignore"
|
|
148
153
|
- CHANGELOG.md
|
|
149
154
|
- Gemfile
|
|
155
|
+
- Gemfile.lock
|
|
150
156
|
- LICENSE.txt
|
|
151
157
|
- README.md
|
|
152
158
|
- Rakefile
|
|
153
159
|
- bin/jdoc
|
|
160
|
+
- example-api-documentation.html
|
|
154
161
|
- example-api-documentation.md
|
|
155
162
|
- jdoc.gemspec
|
|
156
163
|
- lib/jdoc.rb
|
|
@@ -185,8 +192,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
185
192
|
- !ruby/object:Gem::Version
|
|
186
193
|
version: '0'
|
|
187
194
|
requirements: []
|
|
188
|
-
|
|
189
|
-
rubygems_version: 2.2.2
|
|
195
|
+
rubygems_version: 3.5.3
|
|
190
196
|
signing_key:
|
|
191
197
|
specification_version: 4
|
|
192
198
|
summary: Generate API documentation from JSON Schema.
|
|
@@ -194,4 +200,3 @@ test_files:
|
|
|
194
200
|
- spec/fixtures/schema.yml
|
|
195
201
|
- spec/jdoc/generator_spec.rb
|
|
196
202
|
- spec/spec_helper.rb
|
|
197
|
-
has_rdoc:
|