Skip to content

Commit da2dff5

Browse files
mrin9mrin9
committed
updated API documentation and examples
1 parent ea4db77 commit da2dff5

File tree

7 files changed

+278
-32
lines changed

7 files changed

+278
-32
lines changed

‎docs/api.html‎

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -435,6 +435,38 @@ <h2> Attributes</h2>
435435
</td>
436436
<td>false</td>
437437
</tr>
438+
439+
<tr>
440+
<td class="attr-col mono bold right">match-paths</td>
441+
<td class="gray">
442+
If you want to show only few selected APIs based on the target audience,
443+
you may use this attribute to define which paths should be rendered.
444+
The filter can be a simple substring match for a path or can be a complex regex expression.
445+
Wheather to use substring match or regex match is specified through <span class="mono"> match-type</span>
446+
attribute
447+
&nbsp;|&nbsp; <a href="./examples/filter-test.html">Example</a>
448+
</td>
449+
<td>(empty)</td>
450+
</tr>
451+
<tr>
452+
<td class="attr-col mono bold right">match-type</td>
453+
<td class="gray">
454+
<span class='bold dark-gray'>Allowed:<span class='blue'> includes | regex</span></span> -
455+
Defines how <span class="mono"> match-paths</span> is used for filtering
456+
</td>
457+
<td>includes</td>
458+
</tr>
459+
<tr>
460+
<td class="attr-col mono bold right">remove-endpoints-with-badge-label-as</td>
461+
<td class="gray">
462+
Comma separated badge labels to be removed from the spec.
463+
<br/>
464+
You may use vendor-extension <span class="mono">x-badges</span> to assign badges to endpoints.
465+
This attributes helps in removing the endpoints which matches a badge label
466+
&nbsp;|&nbsp; <a href="./examples/filter-test.html">Example</a>
467+
</td>
468+
<td>includes</td>
469+
</tr>
438470
<tr>
439471
<td class="attr-col mono bold right">show-components</td>
440472
<td class="gray">
@@ -1014,9 +1046,18 @@ <h2> Supported vendor extensions</h2>
10141046
<td style="width:130px;"><a href="./examples/code-samples.html"> Usage Example </a> </td>
10151047
</tr>
10161048
<tr id="x-badges">
1017-
<td class="mono bold right" style="width:130px;" >x-badges </td>
1018-
<td class="gray"> Use this vendor-extension to annotate end-points with short color coded lables </td>
1019-
<td style="width:130px;"><a href="./examples/badges.html"> Usage Example </a> </td>
1049+
<td class="mono bold right" style="width:130px;">x-badges </td>
1050+
<td class="gray"> Use this vendor-extension to annotate end-points with short color coded lables.
1051+
You can also assign badges to endpoints and then
1052+
use them with <span class="mono bold">remove-endpoints-with-badge-label-as</span>
1053+
attribute to remove them from your API documentation.
1054+
This allows you to show the same API spec to different groups of audiences.
1055+
Like you want to hide internal APIs for your customers but show then to your developers
1056+
</td>
1057+
<td style="width:130px;">
1058+
<a href="./examples/badges.html"> Badge Example </a><br/>
1059+
<a href="./examples/filter-test.html"> Filter by badge Example </a>
1060+
</td>
10201061
</tr>
10211062

10221063
<tr>

‎docs/examples/badges.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,13 @@
1111
</script>
1212
<meta charset='utf-8'>
1313
<meta name='viewport' content='width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes'>
14+
<!-- script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script -->
1415
<script type='module' src='../rapidoc-min.js'></script>
1516
</head>
1617
<body>
1718
<rapi-doc spec-url="../specs/badges.yaml"
1819
allow-authentication = "false"
20+
allow-server-selection = "false"
1921
theme = "light"
2022
show-info = "true"
2123
show-header = "false"

‎docs/examples/filter-test.html‎

Lines changed: 46 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,25 +19,63 @@
1919
<body>
2020
<rapi-doc id = "thedoc"
2121
spec-url="../specs/filter-test.yaml"
22-
allow-authentication = "false"
23-
show-info = "false"
2422
show-header = "false"
23+
show-info = "true"
24+
allow-server-selection="false"
25+
allow-authentication = "false"
2526
render-style = "read"
27+
use-path-in-nav-bar = "true"
28+
show-method-in-nav-bar = "as-colored-text"
2629
match-paths=""
2730
match-type="includes"
2831
remove-endpoints-with-badge-label-as=""
2932
>
30-
<div slot="operations-top" style="display: flex;justify-content: center; margin: 2px 0">
31-
<input class='size txt' id='filter-text' value="one" type='text' placeholder='filter text' spellcheck='false' style="width:120px">
32-
<button class='btn' style="width:100px" onclick='applyFilter("match-paths")' >Match Paths</button>
33-
<button class='btn' style="width:100px" onclick='applyFilter("remove-endpoints-with-badge-label-as")' >Remove Badge</button>
33+
<div slot="operations-top" style="display: flex;justify-content: center; margin: 16px">
34+
<table style="margin:16px">
35+
<tr>
36+
<td>
37+
complete or partial paths eg: <span class="nono bold">public-path</span>
38+
</td>
39+
<td>
40+
<input id='match-by-path'
41+
class='txt'
42+
value="/public"
43+
type='text'
44+
placeholder='get /public'
45+
spellcheck= "false"
46+
style="width:100px"
47+
>
48+
</td>
49+
<td>
50+
<button class='btn' style="width:170px" onclick='applyFilter("match-by-path")'>Show Only Matching Paths</button>
51+
</td>
52+
</tr>
53+
<tr>
54+
<td>
55+
<span>Comma separated badge labels to remove eg: <span class="nono bold">internal,admin-use-only</span></span>
56+
</td>
57+
<td>
58+
<input id='remove-by-badge'
59+
class='txt'
60+
value="internal"
61+
type='text'
62+
placeholder= "internal,admin-use-only"
63+
spellcheck="false"
64+
style="width:100px"
65+
>
66+
</td>
67+
<td>
68+
<button class='btn' style="width:170px" onclick='applyFilter("remove-by-badge")'>Remove Matching Badges</button>
69+
</td>
70+
</tr>
71+
</table>
3472
</div>
3573
</rapi-doc>
3674
<script>
3775
function applyFilter(filterType) {
3876
const docEl = document.getElementById('thedoc');
39-
const filterText = document.getElementById('filter-text').value || "";
40-
if (filterType === 'match-paths') {
77+
const filterText = document.getElementById(filterType).value || "";
78+
if (filterType === 'match-by-path') {
4179
docEl.setAttribute('remove-endpoints-with-badge-label-as', "");
4280
docEl.setAttribute('match-paths', filterText);
4381
} else {

‎docs/examples/logo.html‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,16 @@
2323
</head>
2424
<body>
2525
<rapi-doc
26-
spec-url="../specs/petstore_extended.yaml"
26+
spec-url="../specs/logo.yaml"
2727
show-header = "false"
2828
render-style = "read"
29-
regular-font="Open Sans"
30-
mono-font = "Roboto Mono"
29+
allow-authentication = "false"
30+
allow-server-selection="false"
3131
>
3232
<div slot="nav-logo" style="display: flex; align-items: center; justify-content: center;">
3333
<img src = "../images/dog.png" style="width:40px; margin-right: 20px"> <span style="color:#fff"> <b>nav-logo</b> slot </span>
3434
</div>
35+
3536
</rapi-doc>
3637
</body>
3738
</html>

‎docs/specs/filter-test.yaml‎

Lines changed: 45 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,72 @@ openapi: 3.0.0
22
info:
33
title: Filtering Endpoints
44
description: |
5-
Test case to check if the Endpoints are removed using the following attributes
6-
- `match-paths`
7-
- `remove-endpoints-with-badge-label-as`
5+
Test case to check if the Endpoints are removed using `match-paths` and `remove-endpoints-with-badge-label-as` attributes
6+
7+
```html
8+
<!-- Only loads the paths which has `users` in it -->
9+
<rapi-doc spec-url = "..." match-paths = "users" />
10+
11+
<!-- Only loads the paths that matches `get /users` so `post /users` wont be loaded -->
12+
<rapi-doc spec-url = "..." match-paths = "get /users" />
13+
14+
<!-- loads the paths using regex matches `^get /users/|^put /users/$` (starts with 'get /users' or 'put /users') -->
15+
<rapi-doc spec-url = "..." match-paths = "^get /users|^put /users" match-type = "regex"/>
16+
17+
<!-- Removes the paths which has badge lable `internal` or `admin-use-only` -->
18+
<rapi-doc spec-url = "..." remove-endpoints-with-badge-label-as = "internal,admin-use-only"/>
19+
```
820
paths:
9-
/path-1:
21+
/internal-path-1:
1022
get:
1123
x-badges:
1224
- color: red
13-
label: Beta
25+
label: Internal
1426
- color: blue
15-
label: one
27+
label: Beta
1628
put:
1729
x-badges:
1830
- color: red
19-
label: Beta
31+
label: Internal
2032
- color: green
21-
label: two
22-
/path-2:
33+
label: Core
34+
/internal-path-2:
2335
get:
2436
x-badges:
25-
- color: primary-color
26-
label: two
37+
- color: red
38+
label: Internal
2739
post:
2840
x-badges:
29-
- color: primary-color
30-
label: three
31-
/path-3:
41+
- color: red
42+
label: Internal
43+
- color: green
44+
label: Core
45+
/public-path-1:
46+
get:
47+
summary: An Endpoint with no badge
48+
/public-path-2:
3249
get:
3350
x-badges:
3451
- color: green
35-
label: two
52+
label: Preffered
53+
/admin-use-only-path-1:
54+
get:
55+
summary: Slow API for Admin's use only
56+
description: Contains a badge `admin-use-only` and `Slow` but notice that `admin-use-only` do not show up in the UI as the badge-color is set to `none`
57+
x-badges:
58+
- color: none
59+
label: admin-use-only
3660
- color: orange
3761
label: Slow
38-
/path-with-hidden-badge:
62+
/admin-use-only-path-2:
3963
get:
40-
description: Contains a badge `four`
64+
summary: Slow API for Admin's use only
65+
description: Contains a badge `admin-use-only` and `Slow` but notice that `admin-use-only` do not show up in the UI as the badge-color is set to `none`
4166
x-badges:
4267
- color: none
43-
label: four
68+
label: admin-use-only
69+
- color: orange
70+
label: Slow
4471
/no-badges-path:
4572
get:
4673
summary: Endpoint with No badges

‎docs/specs/logo.yaml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
openapi: 3.0.0
2+
info:
3+
title: Providing Logo
4+
description: |
5+
Shows how Logos can be inserted using `<slots>` there is a slot named `nav-logo`
6+
<br/><br/>
7+
```html
8+
<!-- using <div slot="nav-logo"> inside <rapi-doc> element -->
9+
<rapi-doc spec-url = "..." >
10+
<div slot="nav-logo" style="display: flex; align-items: center; justify-content: center;">
11+
<img src="../images/dog.png" style="width:40px;">
12+
</div>
13+
</rapi-doc>
14+
```
15+
paths:
16+
/pet:
17+
post:
18+
tags:
19+
- pet
20+
summary: Add a new pet to the store
21+
put:
22+
tags:
23+
- pet
24+
summary: Update an existing pet
25+
/pet/findByStatus:
26+
get:
27+
tags:
28+
- pet
29+
summary: Finds Pets by status
30+
description: Multiple status values can be provided with comma separated strings
31+
/pet/findByTags:
32+
get:
33+
tags:
34+
- pet
35+
summary: Finds Pets by tags
36+
deprecated: true
37+
/store/order:
38+
post:
39+
tags:
40+
- store
41+
summary: Place an order for a pet
42+
/store/order/{orderId}:
43+
get:
44+
tags:
45+
- store
46+
summary: Find purchase order by ID
47+
delete:
48+
tags:
49+
- store
50+
summary: Delete purchase order by ID
51+
/user:
52+
post:
53+
tags:
54+
- user
55+
summary: Create user
56+
/user/{username}:
57+
get:
58+
tags:
59+
- user
60+
summary: Get user by user name
61+
delete:
62+
tags:
63+
- user
64+
summary: Delete user
65+
servers:
66+
- url: https://petstore.swagger.io/v2
67+
- url: http://petstore.swagger.io/v2
68+

‎docs/specs/minimal-petstore.yaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
openapi: 3.0.0
2+
info:
3+
title: Providing Logo
4+
description: |
5+
Shows how COmpany logos can be inserted using `<slots>` there is a slot named `nav-logo`
6+
7+
```html
8+
<!-- Only loads the paths which has `users` in it -->
9+
<rapi-doc spec-url = "..." >
10+
<div slot="nav-logo" style="display: flex; align-items: center; justify-content: center;">
11+
<img src = "../images/dog.png" style="width:40px; margin-right: 20px">
12+
<span style="color:#fff"> <b>nav-logo</b> slot </span>
13+
</div>
14+
</rapi-doc>
15+
```
16+
paths:
17+
/pet:
18+
post:
19+
tags:
20+
- pet
21+
summary: Add a new pet to the store
22+
put:
23+
tags:
24+
- pet
25+
summary: Update an existing pet
26+
/pet/findByStatus:
27+
get:
28+
tags:
29+
- pet
30+
summary: Finds Pets by status
31+
description: Multiple status values can be provided with comma separated strings
32+
/pet/findByTags:
33+
get:
34+
tags:
35+
- pet
36+
summary: Finds Pets by tags
37+
deprecated: true
38+
/store/order:
39+
post:
40+
tags:
41+
- store
42+
summary: Place an order for a pet
43+
/store/order/{orderId}:
44+
get:
45+
tags:
46+
- store
47+
summary: Find purchase order by ID
48+
delete:
49+
tags:
50+
- store
51+
summary: Delete purchase order by ID
52+
/user:
53+
post:
54+
tags:
55+
- user
56+
summary: Create user
57+
/user/{username}:
58+
get:
59+
tags:
60+
- user
61+
summary: Get user by user name
62+
delete:
63+
tags:
64+
- user
65+
summary: Delete user
66+
servers:
67+
- url: https://petstore.swagger.io/v2
68+
- url: http://petstore.swagger.io/v2
69+

0 commit comments

Comments
 (0)