Skip to content

Commit 5fc066a

Browse files
jankapunktjankapunkt
committed
docs: improve api docs
1 parent aac069c commit 5fc066a

File tree

87 files changed

+2620
-2323
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+2620
-2323
lines changed

‎.eslintignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.github
2+
.nyc_output
3+
coverage
4+
docs/*
5+
node_modules

‎CONTRIBUTING.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,3 +165,30 @@ Finally your PR needs to pass the review process:
165165
#### After merge
166166

167167
Please delete your branch after merge.
168+
169+
## Documentation
170+
171+
We use Vitepress+Markdown for our documentation.
172+
If you want to contribute to the docs, please get familiar with Vitepress: https://vitepress.dev
173+
174+
### Setting up docs
175+
176+
You need NPM to setup the docs using the following:
177+
178+
```shell
179+
npm install
180+
npm run docs:setup
181+
```
182+
183+
You can then edit the `guide` section manually.
184+
185+
### API Docs
186+
187+
**DO NOT** edit the `api` section, as API docs are automatically
188+
generated from our internal JSDoc comments.
189+
190+
Instead, update the comments directly within the code and run `npm run docs:api`
191+
to generate the api docs.
192+
193+
### Building the docs
194+

‎docs/.vitepress/cache/deps/_metadata.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
11
{
2-
"hash": "32c93407",
2+
"hash": "24b4e720",
33
"configHash": "34606988",
4-
"lockfileHash": "a556da0f",
5-
"browserHash": "8c9fc86e",
4+
"lockfileHash": "9cc11886",
5+
"browserHash": "4b564f0d",
66
"optimized": {
77
"vue": {
88
"src": "../../../../node_modules/vue/dist/vue.runtime.esm-bundler.js",
99
"file": "vue.js",
10-
"fileHash": "19952a74",
10+
"fileHash": "cc782b89",
1111
"needsInterop": false
1212
},
1313
"vitepress > @vue/devtools-api": {
1414
"src": "../../../../node_modules/@vue/devtools-api/dist/index.js",
1515
"file": "vitepress___@vue_devtools-api.js",
16-
"fileHash": "7e106ad9",
16+
"fileHash": "c1dd3448",
1717
"needsInterop": false
1818
},
1919
"vitepress > @vueuse/core": {
2020
"src": "../../../../node_modules/@vueuse/core/dist/index.js",
2121
"file": "vitepress___@vueuse_core.js",
22-
"fileHash": "db3a86ed",
22+
"fileHash": "372eff28",
2323
"needsInterop": false
2424
}
2525
},

‎docs/.vitepress/config.mts‎

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,32 @@ export default defineConfig({
1010
nav: [
1111
{text: 'Home', link: '/'},
1212
{text: 'Guide', link: '/guide/getting-started'},
13-
{text: 'API', link: '/api/oauth2-server'}
13+
{text: 'API', link: '/api/server'}
1414
],
1515

1616
sidebar: [
1717
{
1818
text: 'Guide',
1919
items: [
2020
{text: 'Getting started', link: '/guide/getting-started'},
21+
{text: 'Grant types', link: '/guide/grant-types'},
2122
{text: 'Model', link: '/guide/model'},
23+
{text: 'Token types', link: '/guide/token-types'},
2224
{text: 'PKCE', link: '/guide/pkce'},
2325
{text: 'Adapters', link: '/guide/adapters'},
24-
{text: 'Extension grants', link: '/guide/extension-grants'},
2526
{text: 'Migrating to v5', link: '/guide/migrating-to-v5'},
27+
{text: 'Contributing', link: '/guide/contributing'},
2628
]
2729
},
2830
{
2931
text: 'API',
3032
items: [
31-
{text: 'OAuth2Server', link: '/api/oauth2-server'},
33+
{text: 'OAuth2Server', link: '/api/server'},
3234
{text: 'Model', link: '/api/model'},
3335
{text: 'Request', link: '/api/request'},
3436
{text: 'Response', link: '/api/response'},
3537
{
3638
text: 'Errors', items: [
37-
{text: 'Overview', link: '/api/errors'},
3839
{text: 'Access Denied', link: '/api/errors/access-denied-error'},
3940
{text: 'Insufficient Scope', link: '/api/errors/insufficient-scope-error'},
4041
{text: 'Invalid Argument', link: '/api/errors/invalid-argument-error'},
@@ -51,6 +52,53 @@ export default defineConfig({
5152
{text: 'Unsupported Response Type', link: '/api/errors/unsupported-response-type-error'},
5253
]
5354
},
55+
{
56+
text: 'Grant Types', items: [
57+
{ text: 'Abstract Grant Type', link: '/api/grant-types/abstract-grant-type' },
58+
{ text: 'Authorization Code', link: '/api/grant-types/authorization-code-grant-type' },
59+
{ text: 'Client Credentials', link: '/api/grant-types/client-credentials-grant-type' },
60+
{ text: 'Password', link: '/api/grant-types/password-grant-type' },
61+
{ text: 'Refresh Token', link: '/api/grant-types/refresh-token-grant-type' },
62+
]
63+
},
64+
{
65+
text: 'Handlers', items: [
66+
{ text: 'Authenticate Handler', link: '/api/handlers/authenticate-handler' },
67+
{ text: 'Authorize Handler', link: '/api/handlers/authorize-handler' },
68+
{ text: 'Token Handler', link: '/api/handlers/token-handler' },
69+
]
70+
},
71+
{
72+
text: 'Models', items: [
73+
{ text: 'Token Model', link: '/api/models/token-model' },
74+
]
75+
},
76+
{
77+
text: 'PKCE', items: [
78+
{ text: 'PKCE', link: '/api/pkce/pkce' },
79+
]
80+
},
81+
{
82+
text: 'Response Types', items: [
83+
{ text: 'Code', link: '/api/response-types/code-response-type' },
84+
{ text: 'Token', link: '/api/response-types/token-response-type' },
85+
]
86+
},
87+
{
88+
text: 'Token Types', items: [
89+
{ text: 'Bearer', link: '/api/token-types/bearer-token-type' },
90+
{ text: 'Mac', link: '/api/token-types/mac-token-type' },
91+
]
92+
},
93+
{
94+
text: 'Utils', items: [
95+
{ text: 'Crypto', link: '/api/utils/crypto-util' },
96+
{ text: 'Date', link: '/api/utils/date-util' },
97+
{ text: 'Scope', link: '/api/utils/scope-util' },
98+
{ text: 'String', link: '/api/utils/string-util' },
99+
{ text: 'Token', link: '/api/utils/token-util' },
100+
]
101+
},
54102
]
55103
}
56104
],

‎docs/api/errors/access-denied-error.md‎

Lines changed: 11 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,16 @@
1-
# AccessDeniedError
1+
<a name="AccessDeniedError"></a>
22

3-
The resource owner or authorization server denied the request. See `Section 4.1.2.1 of RFC 6749 <6749#section-4.1.2.1>`.
3+
## AccessDeniedError
4+
"The resource owner or authorization server denied the request"
45

5-
const AccessDeniedError = require('@node-oauth/oauth2-server/lib/errors/access-denied-error');
6+
**Kind**: global class
7+
**See**: https://tools.ietf.org/html/rfc6749#section-4.1.2.1
8+
<a name="new_AccessDeniedError_new"></a>
69

7-
------------------------------------------------------------------------
10+
### new AccessDeniedError(message, [properties])
811

9-
## `new AccessDeniedError(message, properties)`
12+
| Param | Type |
13+
| --- | --- |
14+
| message | <code>string</code> |
15+
| [properties] | <code>object</code> |
1016

11-
Instantiates an `AccessDeniedError`.
12-
13-
**Arguments:**
14-
15-
| Name | Type | Description |
16-
|-------------------------------------|---------------|-------------------------------------------------------------|
17-
| \[message=undefined\] | String\|Error | See `OAuthError#constructor`. |
18-
| \[properties={}\] | Object | See `OAuthError#constructor`. |
19-
| \[properties.code=400\] | Object | See `OAuthError#constructor`. |
20-
| \[properties.name='access_denied'\] | String | The error name used in responses generated from this error. |
21-
22-
**Return value:**
23-
24-
A new instance of `AccessDeniedError`.
25-
26-
**Remarks:**
27-
28-
const err = new AccessDeniedError();
29-
// err.message === 'Bad Request'
30-
// err.code === 400
31-
// err.name === 'access_denied'
32-
33-
------------------------------------------------------------------------
34-
35-
## `message`
36-
37-
See `OAuthError#message <OAuthError#message>`.
38-
39-
------------------------------------------------------------------------
40-
41-
## `code`
42-
43-
Typically `400`. See `OAuthError#code <OAuthError#code>`.
44-
45-
------------------------------------------------------------------------
46-
47-
## `inner`
48-
49-
See `OAuthError#inner <OAuthError#inner>`.
50-
51-
------------------------------------------------------------------------
52-
53-
## `name`
54-
55-
Typically `'access_denied'`. See `OAuthError#name <OAuthError#name>`.

‎docs/api/errors/index.md‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎docs/api/errors/insufficient-scope-error.md‎

Lines changed: 11 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,16 @@
1-
# InsufficientScopeError
1+
<a name="InsufficientScopeError"></a>
22

3-
The request requires higher privileges than provided by the access token. See `Section 3.1 of RFC 6750 <6750#section-3.1>`.
3+
## InsufficientScopeError
4+
"The request requires higher privileges than provided by the access token.."
45

5-
const InsufficientScopeError = require('@node-oauth/oauth2-server/lib/errors/insufficient-scope-error');
6+
**Kind**: global class
7+
**See**: https://tools.ietf.org/html/rfc6750.html#section-3.1
8+
<a name="new_InsufficientScopeError_new"></a>
69

7-
------------------------------------------------------------------------
10+
### new InsufficientScopeError(message, [properties])
811

9-
## `new InsufficientScopeError(message, properties)`
12+
| Param | Type |
13+
| --- | --- |
14+
| message | <code>string</code> |
15+
| [properties] | <code>object</code> |
1016

11-
Instantiates an `InsufficientScopeError`.
12-
13-
**Arguments:**
14-
15-
| Name | Type | Description |
16-
|------------------------------------------|---------------|-------------------------------------------------------------|
17-
| \[message=undefined\] | String\|Error | See `OAuthError#constructor`. |
18-
| \[properties={}\] | Object | See `OAuthError#constructor`. |
19-
| \[properties.code=403\] | Object | See `OAuthError#constructor`. |
20-
| \[properties.name='insufficient_scope'\] | String | The error name used in responses generated from this error. |
21-
22-
**Return value:**
23-
24-
A new instance of `InsufficientScopeError`.
25-
26-
**Remarks:**
27-
28-
const err = new InsufficientScopeError();
29-
// err.message === 'Forbidden'
30-
// err.code === 403
31-
// err.name === 'insufficient_scope'
32-
33-
------------------------------------------------------------------------
34-
35-
## `message`
36-
37-
See `OAuthError#message <OAuthError#message>`.
38-
39-
------------------------------------------------------------------------
40-
41-
## `code`
42-
43-
Typically `403`. See `OAuthError#code <OAuthError#code>`.
44-
45-
------------------------------------------------------------------------
46-
47-
## `inner`
48-
49-
See `OAuthError#inner <OAuthError#inner>`.
50-
51-
------------------------------------------------------------------------
52-
53-
## `name`
54-
55-
Typically `'insufficient_scope'`. See `OAuthError#name <OAuthError#name>`.

0 commit comments

Comments
 (0)