Skip to content

Commit 5057611

Browse files
mrin9mrin9
committed
updated api documentation
1 parent a5e5016 commit 5057611

File tree

2 files changed

+171
-117
lines changed

2 files changed

+171
-117
lines changed

‎docs/api.html‎

Lines changed: 155 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@
3131
<link rel="stylesheet" href="index.css">
3232

3333
<title>RapiDoc - Web Component based Swagger & OpenAPI Spec Viewer</title>
34+
<style>
35+
.m-table{
36+
width:100%;
37+
}
38+
</style>
3439
</head>
3540

3641
<body>
@@ -62,80 +67,159 @@
6267
<div class="api container" id="api">
6368
<div style="display:flex; flex-direction: column; ">
6469
<h2> Attributes</h2>
65-
<div class="table-block">
70+
<div class='table-block' style="display:flex; flex-direction: column;">
71+
72+
<div class='table-title'> General </div>
6673
<table class="m-table">
6774
<tr>
68-
<th class="attr-col">Attribute</th>
69-
<th style="text-align:left">Description </th>
70-
<th class="default-col">Default</th>
75+
<td class="attr-col mono-bold right">spec-url </td>
76+
<td class="gray">url of the OpenAPI spec to view </td>
77+
<td class='default-col'>(empty)</td>
7178
</tr>
72-
7379
<tr>
74-
<td class="mono-bold right">spec-url </td>
75-
<td class="gray">url of the OpenAPI spec to view </td>
80+
<td class="mono-bold right">heading-text </td>
81+
<td class="gray">Heading Text on top-left corner </td>
7682
<td>(empty)</td>
7783
</tr>
84+
</table>
7885

86+
<div class='table-title'> UI Colors and Fonts </div>
87+
<table class="m-table">
7988
<tr>
80-
<td class="mono-bold right">server-url</td>
81-
<td class="gray">
82-
OpenAPI spec has a provision for providing the server url. The UI will list all the server URLs provided in the spec.
83-
The user can then select one URL to which he or she intends to send API calls while trying out the apis.
84-
However, if you want to provide an API server of your own which is not listed in the spec, you can use this property to provide one.
85-
It is helpful in the cases where the same spec is shared between multiple environment say Dev and Test and each have their own API server.
86-
</td>
87-
<td>(empty)</td>
89+
<td class=" attr-col mono-bold right">theme </td>
90+
<td class="gray"> <span class='bold dark-gray'>Allowed:<span class='blue'> light, dark</span></span> </td>
91+
<td class='default-col'>light</td>
92+
</tr>
93+
<tr>
94+
<td class="mono-bold right">header-color </td>
95+
<td class="gray">Hex color code for the header's background</td>
96+
<td>#444444</td>
8897
</tr>
8998

99+
<tr>
100+
<td class="mono-bold right">primary-color</td>
101+
<td class="gray">Hex color code on various controls such as buttons, tabs </td>
102+
<td>#FF791A</td>
103+
</tr>
104+
105+
<tr>
106+
<td class="mono-bold right">regular-font </td>
107+
<td class="gray">Font Name(s) to be used for regular text </td>
108+
<td>rapidoc, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif</td>
109+
</tr>
110+
111+
<tr>
112+
<td class="mono-bold right">mono-font </td>
113+
<td class="gray">Font Name(s) to be used for monospaced text </td>
114+
<td>Monaco, 'Andale Mono', 'Roboto Mono', 'Consolas'</td>
115+
</tr>
116+
</table>
117+
118+
<div class='table-title'> Navigation bar colors (only applicable in read-mode)</div>
119+
<table class="m-table">
120+
<tr>
121+
<td class=" attr-col mono-bold right">nav-bg-color </td>
122+
<td class="gray"> <span class='bold dark-gray'>Navigation bar's background color</span></span> </td>
123+
<td class='default-col'></td>
124+
</tr>
125+
<tr>
126+
<td class=" attr-col mono-bold right">nav-text-color </td>
127+
<td class="gray"> <span class='bold dark-gray'>Navigation bar's Text color</span></span> </td>
128+
<td class='default-col'></td>
129+
</tr>
130+
<tr>
131+
<td class=" attr-col mono-bold right">nav-hover-bg-color </td>
132+
<td class="gray"> <span class='bold dark-gray'>background color of the navigation item on mouse-over</span></span> </td>
133+
<td class='default-col'></td>
134+
</tr>
135+
<tr>
136+
<td class=" attr-col mono-bold right">nav-hover-text-color </td>
137+
<td class="gray"> <span class='bold dark-gray'>text color of the navigation item on mouse-over</span></span> </td>
138+
<td class='default-col'></td>
139+
</tr>
140+
<tr>
141+
<td class=" attr-col mono-bold right">nav-accent-color </td>
142+
<td class="gray"> <span class='bold dark-gray'>Current selected item indicator</span></span> </td>
143+
<td class='default-col'></td>
144+
</tr>
145+
</table>
146+
147+
<div class='table-title'> UI Layout & Placement</div>
148+
<table class="m-table">
149+
<tr>
150+
<td class="attr-col mono-bold right"> layout </td>
151+
<td class="gray"> <span class='bold dark-gray'>Allowed:<span class='blue'> row, column</span></span>
152+
Layout helps in placement of request/response sections. In column layout, request & response sections are placed one below the other,
153+
In row layout they are placed side by side.
154+
This attribute is applicable only when the device width is more than 768px and the render-style is 'view'.
155+
</td>
156+
<td class='default-col'>row</td>
157+
</tr>
158+
<tr>
159+
<td class="mono-bold right">schema-style </td>
160+
<td class="gray"> <span class='bold dark-gray'>Allowed:<span class='blue'> tree, table</span></span> - Two different ways to display object-schemas in the responses and request bodies </td>
161+
<td>tree</td>
162+
</tr>
163+
<tr>
164+
<td class="mono-bold right">render-style </td>
165+
<td class="gray"><span class='bold dark-gray'>Allowed:<span class='blue'> read, view</span></span> - determines display of api-docs. Currently there are two modes supported.
166+
'read' - more suitable for reading and 'view' more frendly for quick exploring </td>
167+
<td>view</td>
168+
</tr>
90169
<tr>
91170
<td class="mono-bold right">api-list-style</td>
92171
<td class="gray">
93-
can be either <code>group-by-tag</code> or <code> group-by-path </code>. This controls how the API litings are grouped.
94-
this can be changed from the UI too
172+
<span class='bold dark-gray'>Allowed:<span class='blue'> group-by-tag, group-by-path</span></span> -
173+
This controls how the API litings are grouped. this can be changed from the UI too (applied only in view mode)
95174
</td>
96175
<td>group-by-tag</td>
97176
</tr>
98-
99177
<tr>
100-
<td class="mono-bold right">allow-authentication</td>
178+
<td class="mono-bold right">default-schema-tab</td>
101179
<td class="gray">
102-
Authentication feature, allows the user to select one of the authentication mechanism thats available in the spec.
103-
It can be http-basic, http-bearer or api-key.
104-
If you dont want your users to go through the authentication process, instead want them to use a pre-generated api-key
105-
then you may hide authentication section by setting this attribute to false
106-
and provide the api-key details using various api-key-???? attributes.</td>
107-
<td>true</td>
180+
<span class='bold dark-gray'>Allowed:<span class='blue'> model, example</span></span> -
181+
The schemas are displayed in two tabs - Model and Example.
182+
This option allows you to pick the default tab that you would like to be active
183+
</td>
184+
<td>model</td>
108185
</tr>
186+
</table>
109187

188+
<div class='table-title'> Hide/Show Sections </div>
189+
<table class="m-table">
110190
<tr>
111-
<td class="mono-bold right">api-key-name</td>
112-
<td class="gray">Name of the API key that will be send while trying out the APIs</td>
113-
<td>Authorization</td>
191+
<td class="attr-col mono-bold right">show-info</td>
192+
<td class="gray">
193+
show/hide the documents info section<br/>
194+
Info section contains information about the spec, such as the title and description of the spec, the version, terms of services etc.
195+
In certain situation you may not need to show this section. For instance you are embedding this element inside a another help document.
196+
Chances are, the help doc may already have this info, in that case you may want to hide this section.
197+
</td>
198+
<td>true</td>
114199
</tr>
115-
116200
<tr>
117-
<td class="mono-bold right">api-key-value</td>
118-
<td class="gray">Value of the API key that will be send while trying out the APIs</td>
119-
<td>(empty)</td>
201+
<td class="mono-bold right">show-header </td>
202+
<td class="gray">show/hide the header.<br/>
203+
If you dont want your user to open any other api spec, other than the current one, then set this attribute to false</td>
204+
<td class='default-col'> true</td>
120205
</tr>
121-
122206
<tr>
123-
<td class="mono-bold right">api-key-location</td>
207+
<td class="mono-bold right">allow-authentication</td>
124208
<td class="gray">
125-
determines how you want to send the api-key.
126-
allowed values are <code>header</code> or <code> query </code>
127-
</td>
128-
<td>header</td>
209+
Authentication feature, allows the user to select one of the authentication mechanism thats available in the spec.
210+
It can be http-basic, http-bearer or api-key.
211+
If you dont want your users to go through the authentication process, instead want them to use a pre-generated api-key
212+
then you may hide authentication section by setting this attribute to false
213+
and provide the api-key details using various api-key-???? attributes.</td>
214+
<td>true</td>
129215
</tr>
130-
131216
<tr>
132217
<td class="mono-bold right">allow-spec-url-load</td>
133218
<td class="gray">
134219
If set to 'false', user will not be able to load any spec url from the UI.
135220
</td>
136221
<td>true</td>
137222
</tr>
138-
139223
<tr>
140224
<td class="mono-bold right">allow-spec-file-load</td>
141225
<td class="gray">
@@ -144,15 +228,13 @@ <h2> Attributes</h2>
144228
</td>
145229
<td>true</td>
146230
</tr>
147-
148231
<tr>
149232
<td class="mono-bold right">allow-search</td>
150233
<td class="gray">
151234
If set to 'false', user will not be able to search APIs.
152235
</td>
153236
<td>true</td>
154237
</tr>
155-
156238
<tr>
157239
<td class="mono-bold right">allow-try</td>
158240
<td class="gray">
@@ -161,7 +243,6 @@ <h2> Attributes</h2>
161243
</td>
162244
<td>true</td>
163245
</tr>
164-
165246
<tr>
166247
<td class="mono-bold right">allow-server-selection</td>
167248
<td class="gray">
@@ -170,93 +251,58 @@ <h2> Attributes</h2>
170251
</td>
171252
<td>true</td>
172253
</tr>
173-
<tr>
174-
<td class="mono-bold right">default-api-server</td>
175-
<td class="gray">
176-
Use this attribute, if you have defined multiple API-Servers defined in the sepc and want to set a default one which will be used while trying out the APIs
177-
</td>
178-
<td>(empty)</td>
179-
</tr>
180254
<tr>
181255
<td class="mono-bold right">allow-api-list-style-selection</td>
182256
<td class="gray">
183257
If set to 'false', user will not be able to change api list style
184258
</td>
185259
<td>true</td>
186260
</tr>
261+
</table>
187262

263+
<div class='table-title'> API Server</div>
264+
<table class="m-table">
188265
<tr>
189-
<td class="mono-bold right">show-info</td>
190-
<td class="gray">
191-
show/hide the documents info section<br/>
192-
Info section contains information about the spec, such as the title and description of the spec, the version, terms of services etc.
193-
In certain situation you may not need to show this section. For instance you are embedding this element inside a another help document.
194-
Chances are, the help doc may already have this info, in that case you may want to hide this section.
195-
</td>
196-
<td>true</td>
197-
</tr>
198-
199-
<tr>
200-
<td class="mono-bold right">show-header </td>
201-
<td class="gray">show/hide the header.<br/>
202-
If you dont want your user to open any other api spec, other than the current one, then set this attribute to false</td>
203-
<td>true</td>
266+
<td class="attr-col mono-bold right">api-key-name</td>
267+
<td class="gray">Name of the API key that will be send while trying out the APIs</td>
268+
<td class='default-col'>Authorization</td>
204269
</tr>
205-
206270
<tr>
207-
<td class="mono-bold right">heading-text </td>
208-
<td class="gray">Heading Text on top-left corner </td>
271+
<td class="mono-bold right">api-key-value</td>
272+
<td class="gray">
273+
Value of the API key that will be send while trying out the APIs.
274+
This can also be provided/overwritted from UI.
275+
</td>
209276
<td>(empty)</td>
210277
</tr>
211-
212278
<tr>
213-
<td class="mono-bold right">header-color </td>
214-
<td class="gray">Hex color code for the header's background</td>
215-
<td>#444444</td>
216-
</tr>
217-
218-
<tr>
219-
<td class="mono-bold right">primary-color</td>
220-
<td class="gray">Hex color code on various controls such as buttons, tabs </td>
221-
<td>#FF791A</td>
222-
</tr>
223-
224-
<tr>
225-
<td class="mono-bold right">regular-font </td>
226-
<td class="gray">Font Name(s) to be used for regular text </td>
227-
<td>rapidoc, Helvetica, Arial</td>
228-
</tr>
229-
230-
<tr>
231-
<td class="mono-bold right">mono-font </td>
232-
<td class="gray">Font Name(s) to be used for monospaced text </td>
233-
<td>Monaco, 'Andale Mono', 'Roboto Mono'</td>
234-
</tr>
235-
<tr>
236-
<td class="mono-bold right">theme </td>
237-
<td class="gray">light, dark </td>
238-
<td>light</td>
239-
</tr>
240-
<tr>
241-
<td class="mono-bold right">schema-style </td>
242-
<td class="gray">tree, table (there are two different ways to display object-schemas in the responses and request bodies) </td>
243-
<td>tree</td>
279+
<td class="mono-bold right">api-key-location</td>
280+
<td class="gray">
281+
<span class='bold dark-gray'>Allowed:<span class='blue'> header, query</span></span> -
282+
determines how you want to send the api-key.
283+
</td>
284+
<td>header</td>
244285
</tr>
245286
<tr>
246-
<td class="mono-bold right">render-style </td>
247-
<td class="gray">read, view</td>
248-
<td>view</td>
287+
<td class="mono-bold right">server-url</td>
288+
<td class="gray">
289+
OpenAPI spec has a provision for providing the server url. The UI will list all the server URLs provided in the spec.
290+
The user can then select one URL to which he or she intends to send API calls while trying out the apis.
291+
However, if you want to provide an API server of your own which is not listed in the spec, you can use this property to provide one.
292+
It is helpful in the cases where the same spec is shared between multiple environment say Dev and Test and each have their own API server.
293+
</td>
294+
<td>(empty)</td>
249295
</tr>
250296
<tr>
251-
<td class="mono-bold right"> layout </td>
252-
<td class="gray">Applicable only when render-style='view' layout helps in placement of your request/response sections. The allowed values are 'row' or 'column'.
253-
In column layout, request & response sections are placed one below the other,
254-
In row layout request & response sections are placed side by side.
255-
This attribute is applicable only when the device width is more than 768px.
297+
<td class="mono-bold right">default-api-server</td>
298+
<td class="gray">
299+
If you have multiple api-server listed in the spec, use this attribute to select the default API server, where all the API calls will goto.
300+
This can be changed later from the UI
256301
</td>
257-
<td>row</td>
302+
<td>(Empty)</td>
258303
</tr>
259304
</table>
305+
260306
</div>
261307

262308
<h2> Methods </h2>

0 commit comments

Comments
 (0)