Skip to content

Commit 6d1de2a

Browse files
ruslanbaidanruslanbaidan
authored
Merge pull request #571
Add Swagger UI renderer and comprehensive API documentation
2 parents fe5741e + e71f10d commit 6d1de2a

File tree

4 files changed

+2681
-166
lines changed

4 files changed

+2681
-166
lines changed

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,25 @@ For installation instructions see
4646

4747
You can also use the provided [Virtual Machine](https://vm.monarc.lu).
4848

49+
API Documentation
50+
-----------------
51+
52+
MONARC provides a comprehensive RESTful API for programmatic access. The API is documented using OpenAPI 3.0 (Swagger) specification.
53+
54+
- **View API Documentation**: Navigate to `/swagger-ui.html` in your MONARC installation
55+
- **OpenAPI Specification**: Available at `/swagger.yaml`
56+
- **Documentation Guide**: See [public/API_DOCUMENTATION.md](public/API_DOCUMENTATION.md)
57+
58+
The API allows you to:
59+
- Manage risk analyses (ANR)
60+
- Handle assets, threats, and vulnerabilities
61+
- Manage risks and operational risks
62+
- Create and track recommendations
63+
- Generate reports and exports
64+
- And much more...
65+
66+
Authentication is token-based. See the API documentation for details on obtaining and using authentication tokens.
67+
4968

5069
Development Environment
5170
-----------------------

‎public/API_DOCUMENTATION.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# MONARC API Documentation
2+
3+
This directory contains the OpenAPI specification and Swagger UI for the MONARC API.
4+
5+
## Files
6+
7+
- `swagger.yaml` - OpenAPI 3.0.0 specification describing all MONARC API endpoints
8+
- `swagger-ui.html` - Web interface for viewing and interacting with the API documentation
9+
10+
## Accessing the API Documentation
11+
12+
### Option 1: View in Browser (Recommended for local installations)
13+
14+
If you have MONARC running locally, navigate to:
15+
```
16+
http://your-monarc-installation/swagger-ui.html
17+
```
18+
19+
### Option 2: Download and Use Swagger Editor
20+
21+
1. Download the `swagger.yaml` file
22+
2. Visit [Swagger Editor](https://editor.swagger.io/)
23+
3. Import the `swagger.yaml` file
24+
25+
### Option 3: Use with API Clients
26+
27+
Import the `swagger.yaml` file into API testing tools:
28+
- Postman
29+
- Insomnia
30+
- HTTPie
31+
- Or any OpenAPI-compatible tool
32+
33+
## Authentication
34+
35+
Most API endpoints require authentication. To authenticate:
36+
37+
1. **Login**: Send a POST request to `/api/auth` with your credentials:
38+
```json
39+
{
40+
"email": "[email protected]",
41+
"password": "your-password"
42+
}
43+
```
44+
45+
2. **Use Token**: Include the returned token in subsequent requests using the `Token` header:
46+
```
47+
Token: your-authentication-token
48+
```
49+
50+
## API Endpoints Overview
51+
52+
The API is organized into the following categories:
53+
54+
- **Authentication** - User login and logout
55+
- **Users** - User management (admin only)
56+
- **Roles** - User role management
57+
- **ANR** - Risk analysis management
58+
- **Assets** - Asset management within analyses
59+
- **Threats** - Threat management
60+
- **Vulnerabilities** - Vulnerability management
61+
- **Measures** - Control/measure management
62+
- **Risks** - Risk assessment and management
63+
- **Recommendations** - Recommendation management
64+
- **Treatment Plan** - Risk treatment planning
65+
- **SOA** - Statement of Applicability
66+
- **Records (GDPR)** - Processing activities records
67+
- **Instances** - Asset instances in risk analyses
68+
- **Snapshots** - Analysis snapshots
69+
- **Statistics** - Statistical data
70+
- And many more...
71+
72+
## Base URL
73+
74+
All API endpoints are relative to your MONARC installation's base URL.
75+
76+
For example:
77+
- Local: `http://localhost/api/...`
78+
- Production: `https://your-domain.com/api/...`
79+
80+
## API Versioning
81+
82+
The current API version is documented in the `swagger.yaml` file (version 2.13.3 as of this update).
83+
84+
## Contributing
85+
86+
When adding new API endpoints:
87+
88+
1. Update the route configuration in `config/module.config.php`
89+
2. Add the endpoint documentation to `public/swagger.yaml`
90+
3. Ensure proper authentication and authorization are documented
91+
4. Include request/response examples where applicable
92+
93+
## Support
94+
95+
For more information about MONARC:
96+
- Website: https://www.monarc.lu
97+
- Documentation: https://www.monarc.lu/documentation
98+
- GitHub: https://github.com/monarc-project

‎public/swagger-ui.html‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>MONARC API Documentation</title>
7+
<style>
8+
html {
9+
box-sizing: border-box;
10+
overflow: -moz-scrollbars-vertical;
11+
overflow-y: scroll;
12+
}
13+
14+
*,
15+
*:before,
16+
*:after {
17+
box-sizing: inherit;
18+
}
19+
20+
body {
21+
margin: 0;
22+
padding: 0;
23+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
24+
}
25+
26+
.swagger-info {
27+
max-width: 1200px;
28+
margin: 0 auto;
29+
padding: 40px 20px;
30+
}
31+
32+
h1 {
33+
color: #3b4151;
34+
font-size: 2.5em;
35+
margin-bottom: 20px;
36+
}
37+
38+
.description {
39+
color: #3b4151;
40+
font-size: 1.1em;
41+
line-height: 1.6;
42+
margin-bottom: 30px;
43+
}
44+
45+
.download-link {
46+
display: inline-block;
47+
padding: 12px 24px;
48+
background-color: #4990e2;
49+
color: white;
50+
text-decoration: none;
51+
border-radius: 4px;
52+
font-size: 1em;
53+
margin-right: 10px;
54+
margin-bottom: 10px;
55+
}
56+
57+
.download-link:hover {
58+
background-color: #357abd;
59+
}
60+
61+
.external-link {
62+
display: inline-block;
63+
padding: 12px 24px;
64+
background-color: #49cc90;
65+
color: white;
66+
text-decoration: none;
67+
border-radius: 4px;
68+
font-size: 1em;
69+
margin-bottom: 10px;
70+
}
71+
72+
.external-link:hover {
73+
background-color: #3da574;
74+
}
75+
76+
.instructions {
77+
background-color: #f7f7f7;
78+
padding: 20px;
79+
border-radius: 4px;
80+
margin-top: 30px;
81+
}
82+
83+
.instructions h2 {
84+
color: #3b4151;
85+
margin-top: 0;
86+
}
87+
88+
.instructions ol {
89+
line-height: 1.8;
90+
}
91+
92+
.instructions code {
93+
background-color: #e7e7e7;
94+
padding: 2px 6px;
95+
border-radius: 3px;
96+
font-family: monospace;
97+
}
98+
</style>
99+
</head>
100+
<body>
101+
<div class="swagger-info">
102+
<h1>MONARC API Documentation</h1>
103+
104+
<div class="description">
105+
<p>Welcome to the MONARC (Optimised Risk Analysis Method) API documentation.</p>
106+
<p>This API allows you to programmatically interact with MONARC for risk analysis, asset management, threat assessment, and more.</p>
107+
</div>
108+
109+
<div>
110+
<a href="swagger.yaml" class="download-link" download>Download OpenAPI Specification (YAML)</a>
111+
<a href="https://editor.swagger.io/?url=" class="external-link" target="_blank" id="swagger-editor">View in Swagger Editor</a>
112+
</div>
113+
114+
<div class="instructions">
115+
<h2>How to View the API Documentation</h2>
116+
<ol>
117+
<li><strong>Download the specification:</strong> Click the "Download OpenAPI Specification" button above to get the <code>swagger.yaml</code> file.</li>
118+
<li><strong>Use Swagger Editor:</strong> Click the "View in Swagger Editor" button to view the documentation in the online Swagger Editor.</li>
119+
<li><strong>Use Swagger UI locally:</strong> If you have Swagger UI installed locally, you can load the <code>swagger.yaml</code> file from <code>/public/swagger.yaml</code> path.</li>
120+
<li><strong>Import into API clients:</strong> Import the OpenAPI specification into tools like Postman, Insomnia, or other API clients for testing.</li>
121+
</ol>
122+
123+
<h2>Authentication</h2>
124+
<p>Most API endpoints require authentication via a <code>Token</code> header. To authenticate:</p>
125+
<ol>
126+
<li>Login via <code>POST /api/auth</code> with your email and password</li>
127+
<li>Include the returned token in subsequent requests using the <code>Token</code> header</li>
128+
</ol>
129+
130+
<h2>Base URL</h2>
131+
<p>All API endpoints are relative to the base URL of your MONARC installation.</p>
132+
</div>
133+
</div>
134+
135+
<script>
136+
// Set the correct URL for Swagger Editor with the current server's swagger.yaml
137+
const swaggerEditorLink = document.getElementById('swagger-editor');
138+
const currentUrl = window.location.href.replace('swagger-ui.html', 'swagger.yaml');
139+
swaggerEditorLink.href = 'https://editor.swagger.io/?url=' + encodeURIComponent(currentUrl);
140+
</script>
141+
</body>
142+
</html>

0 commit comments

Comments
 (0)