@strapi/openapi 5.47.1 → 5.48.1
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.
- package/README.md +76 -0
- package/dist/index.js +2 -2
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1 +1,77 @@
|
|
|
1
1
|
# @strapi/openapi
|
|
2
|
+
|
|
3
|
+
`@strapi/openapi` provides the core OpenAPI generation pipeline used by Strapi.
|
|
4
|
+
|
|
5
|
+
## Generate a specification
|
|
6
|
+
|
|
7
|
+
You can generate a document from the CLI:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
strapi openapi generate
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This command generates a `content-api` specification by default.
|
|
14
|
+
|
|
15
|
+
## Expose `/openapi.json` from the server
|
|
16
|
+
|
|
17
|
+
Strapi can expose a generated OpenAPI document over HTTP. Both endpoints are
|
|
18
|
+
disabled by default; opt in per endpoint via `server.openapi`:
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
// config/server.js
|
|
22
|
+
module.exports = () => ({
|
|
23
|
+
openapi: {
|
|
24
|
+
'content-api': {
|
|
25
|
+
// 'disabled' (default) | 'public'
|
|
26
|
+
access: 'public',
|
|
27
|
+
route: {
|
|
28
|
+
path: '/openapi.json',
|
|
29
|
+
},
|
|
30
|
+
cache: {
|
|
31
|
+
enabled: true,
|
|
32
|
+
maxAgeMs: 60_000,
|
|
33
|
+
filePath: '.strapi/openapi/content-api.json',
|
|
34
|
+
},
|
|
35
|
+
},
|
|
36
|
+
admin: {
|
|
37
|
+
// 'disabled' (default) | 'authenticated' ('public' is not allowed)
|
|
38
|
+
access: 'authenticated',
|
|
39
|
+
route: {
|
|
40
|
+
path: '/openapi.json',
|
|
41
|
+
},
|
|
42
|
+
cache: {
|
|
43
|
+
enabled: true,
|
|
44
|
+
maxAgeMs: 60_000,
|
|
45
|
+
filePath: '.strapi/openapi/admin.json',
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
},
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Options
|
|
53
|
+
|
|
54
|
+
- `server.openapi['content-api']`: config for the Content API OpenAPI endpoint.
|
|
55
|
+
- `server.openapi.admin`: config for the Admin API OpenAPI endpoint.
|
|
56
|
+
- `access`: controls exposure and protection in a single setting (default `disabled`). See below.
|
|
57
|
+
- `route.path`: endpoint subpath to register (resolved under `/api` for content-api and under `/admin` for admin by default).
|
|
58
|
+
- `cache.enabled`: enables file-based cache for generated output.
|
|
59
|
+
- `cache.maxAgeMs`: cache validity in milliseconds.
|
|
60
|
+
- `cache.filePath`: output file path for cached spec (absolute or app-root relative).
|
|
61
|
+
|
|
62
|
+
### Access control
|
|
63
|
+
|
|
64
|
+
A single `access` value per endpoint controls both whether the endpoint exists and how it is protected.
|
|
65
|
+
Access is governed by Strapi's existing auth, not by a bespoke access surface:
|
|
66
|
+
|
|
67
|
+
- `disabled` (default): the endpoint is not registered.
|
|
68
|
+
- `public` (**content-api only**): no authentication — anyone can read the spec.
|
|
69
|
+
- `authenticated` (**admin only**): requires an authenticated admin (any role). Granular
|
|
70
|
+
per-permission RBAC is intentionally left for a later iteration.
|
|
71
|
+
|
|
72
|
+
The content-api endpoint is only available as public for now. The admin endpoint is never public.
|
|
73
|
+
Unsupported access values throw at startup.
|
|
74
|
+
|
|
75
|
+
> **Security note:** a `public` content-api spec describes your entire Content API surface — including
|
|
76
|
+
> content types that are not publicly readable — to anyone. If you need a gated spec, use the admin
|
|
77
|
+
> endpoint with `authenticated`. Review who can reach each endpoint before enabling it.
|
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@strapi/openapi",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.48.1",
|
|
4
4
|
"description": "A tool set to help generate and validate API documentation for Strapi projects",
|
|
5
5
|
"homepage": "https://strapi.io",
|
|
6
6
|
"bugs": {
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
"test:unit:watch": "run -T jest --watch"
|
|
54
54
|
},
|
|
55
55
|
"engines": {
|
|
56
|
-
"node": ">=20.0.0 <=
|
|
56
|
+
"node": ">=20.0.0 <=26.x.x",
|
|
57
57
|
"npm": ">=6.0.0"
|
|
58
58
|
},
|
|
59
59
|
"dependencies": {
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"zod": "3.25.67"
|
|
63
63
|
},
|
|
64
64
|
"devDependencies": {
|
|
65
|
-
"@strapi/types": "5.
|
|
65
|
+
"@strapi/types": "5.48.1",
|
|
66
66
|
"@types/debug": "^4"
|
|
67
67
|
}
|
|
68
68
|
}
|