xypriss-swagger 1.0.30 → 1.0.32
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 +146 -0
- package/package.json +1 -1
- package/xypriss.plugin.xsig +5 -6
package/README.md
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# XyPriss Swagger Plugin
|
|
2
|
+
|
|
3
|
+
The **XyPriss Swagger Plugin** is a high-performance auto-documentation tool for the XyPriss ecosystem. It automatically generates OpenAPI 3.0 specifications by introspecting the XyPriss route registry and serves a beautiful Swagger UI through an isolated auxiliary server.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Auto-Generation**: Automatically extracts routes, methods, path parameters, and guards from the XyPriss engine.
|
|
8
|
+
- **Isolated Serving**: Uses an auxiliary server to serve the documentation, keeping your main application logic clean and secure.
|
|
9
|
+
- **Zero-Trust Compatible**: Integrates with XyPriss security layers and handles route-level guards.
|
|
10
|
+
- **Micro-Services Ready**: Each instance can be configured with its own port and path.
|
|
11
|
+
- **High-Performance Streaming**: Swagger UI is served using Node.js Transform streams for zero-buffer, high-speed delivery.
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Install the plugin via XFPM:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
xfpm add xypriss-swagger
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Usage
|
|
22
|
+
|
|
23
|
+
### 1. Register the Plugin
|
|
24
|
+
|
|
25
|
+
In your main XyPriss application, import and register the `SwaggerPlugin`:
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { SwaggerPlugin } from "xypriss-swagger";
|
|
29
|
+
import { XyPrissServer } from "xypriss";
|
|
30
|
+
|
|
31
|
+
const server = new XyPrissServer();
|
|
32
|
+
|
|
33
|
+
server.use(
|
|
34
|
+
SwaggerPlugin({
|
|
35
|
+
port: 7070, // Port for the documentation server
|
|
36
|
+
path: "/docs", // Path to access the Swagger UI
|
|
37
|
+
title: "My API", // Documentation title
|
|
38
|
+
version: "1.0.0", // API Version
|
|
39
|
+
}),
|
|
40
|
+
);
|
|
41
|
+
|
|
42
|
+
server.start();
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### 2. Configure Plugin Access
|
|
46
|
+
|
|
47
|
+
Ensure the plugin is authorized in your `xypriss.config.jsonc`:
|
|
48
|
+
|
|
49
|
+
```jsonc
|
|
50
|
+
{
|
|
51
|
+
"$internal": {
|
|
52
|
+
"xypriss-swagger": {
|
|
53
|
+
"type": "plugin",
|
|
54
|
+
"__meta__": {
|
|
55
|
+
"path": "ROOT://",
|
|
56
|
+
},
|
|
57
|
+
"__xfs__": {
|
|
58
|
+
"path": "CWD://",
|
|
59
|
+
},
|
|
60
|
+
"permissions": {
|
|
61
|
+
"allowedHooks": [
|
|
62
|
+
"PLG.OPS.AUXILIARY_SERVER",
|
|
63
|
+
"PLG.SECURITY.ACCESS_CONFIGS",
|
|
64
|
+
],
|
|
65
|
+
"policy": "allow",
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
},
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Configuration Options
|
|
73
|
+
|
|
74
|
+
| Option | Type | Default | Description |
|
|
75
|
+
| :------------ | :------- | :-------------------- | :------------------------------------------------------------------------ |
|
|
76
|
+
| `port` | `number` | `7070` | The port on which the auxiliary Swagger server will run. |
|
|
77
|
+
| `path` | `string` | `"/docs"` | The base path for the documentation (e.g., `http://localhost:7070/docs`). |
|
|
78
|
+
| `title` | `string` | `"API Documentation"` | The title displayed in the Swagger UI. |
|
|
79
|
+
| `version` | `string` | `"1.0.0"` | The version of the API documentation. |
|
|
80
|
+
| `description` | `string` | plugin description | Brief description of your API. |
|
|
81
|
+
|
|
82
|
+
## Security & Trust
|
|
83
|
+
|
|
84
|
+
To use this plugin in a zero-trust environment, you must trust the developer ID.
|
|
85
|
+
|
|
86
|
+
> [!IMPORTANT]
|
|
87
|
+
> **Developer ID**: `ed25519:a58b17a3e46302dd3ae5538bc9b8b991c57f4c5fe2e7d8ac41803de818d947f4`
|
|
88
|
+
|
|
89
|
+
### Enrollment
|
|
90
|
+
|
|
91
|
+
When prompted by XFPM, paste the Developer ID above to authorize its execution.
|
|
92
|
+
|
|
93
|
+
## Documentation Access
|
|
94
|
+
|
|
95
|
+
Once the server is started, you can access:
|
|
96
|
+
|
|
97
|
+
- **Swagger UI**: `http://localhost:7070/docs`
|
|
98
|
+
- **OpenAPI JSON**: `http://localhost:7070/docs/swagger.json`
|
|
99
|
+
|
|
100
|
+
## Advanced: Route Metadata
|
|
101
|
+
|
|
102
|
+
You can customize the documentation for individual routes by adding metadata:
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
server.get(
|
|
106
|
+
"/users/:id",
|
|
107
|
+
(req, res) => {
|
|
108
|
+
// ...
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
meta: {
|
|
112
|
+
summary: "Get user by ID",
|
|
113
|
+
tags: ["Users"],
|
|
114
|
+
openapi: {
|
|
115
|
+
responses: {
|
|
116
|
+
"200": {
|
|
117
|
+
description: "User found",
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
},
|
|
122
|
+
},
|
|
123
|
+
);
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
> [!NOTE]
|
|
127
|
+
> For a deep dive into how XyPriss manages plugin isolation and filesystem access, see the [Workspace System Guide](../core/WORKSPACE_SYSTEM.md).
|
|
128
|
+
|
|
129
|
+
## Security & Permissions
|
|
130
|
+
|
|
131
|
+
In order to properly analyze your project's codebase and generate accurate Swagger documentation, this plugin requires the `CWD://` (Current Working Directory) context permission.
|
|
132
|
+
|
|
133
|
+
**Why is `CWD://` required?**
|
|
134
|
+
The plugin needs to resolve the active execution directory to dynamically scan your route files, interpret comments, and compile the OpenAPI JSON structure correctly.
|
|
135
|
+
|
|
136
|
+
**Is it safe?**
|
|
137
|
+
Absolutely. While `CWD://` grants broad access to the project root, the XyPriss Swagger plugin is an official, strictly audited core module. It **exclusively** performs safe, read-only operations targeting your router files. It explicitly ignores sensitive system files (e.g., `.env`, credentials) and does not leak or alter your business logic. Your environment remains completely secure.
|
|
138
|
+
|
|
139
|
+
## License
|
|
140
|
+
|
|
141
|
+
Provided under the Nehonix Open Source License (NOSL) v1.0. Check the included LICENSE file for comprehensive terms.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
**By [Nehonix](https://github.com/Nehonix-Team)**
|
|
146
|
+
|
package/package.json
CHANGED
package/xypriss.plugin.xsig
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
--- XYPRISS SIGNATURE (G3) ---
|
|
2
|
-
Manifest: xypriss-swagger@1.0.
|
|
3
|
-
Min-Engine: 1.0.
|
|
4
|
-
Fingerprint: sha256:
|
|
2
|
+
Manifest: xypriss-swagger@1.0.32
|
|
3
|
+
Min-Engine: 1.0.31
|
|
4
|
+
Fingerprint: sha256:214f4f7bc77e35b3bb2a3ed928be809176a6ed624c6944d11c46291ad2647e7a
|
|
5
5
|
Identity: ed25519:a58b17a3e46302dd3ae5538bc9b8b991c57f4c5fe2e7d8ac41803de818d947f4
|
|
6
|
-
Expires: 2027-04-
|
|
6
|
+
Expires: 2027-04-21T21:34:19Z
|
|
7
7
|
Revision: sha256:none
|
|
8
|
-
|
|
9
8
|
--- BEGIN CRYPTOGRAPHIC PROOF ---
|
|
10
|
-
base64:
|
|
9
|
+
base64:jzOJWJCHGxXr1oF02d5BuSUQqw/jFFPNc2uVH6DbFsyttXnmFQkEsaamg9QdPKyIiFOtIySFkRFicrvsMykzDg==
|
|
11
10
|
--- END XYPRISS SIGNATURE ---
|