Skip to content

Commit 3a0d7d5

Browse files
Copilotzmoog
Copilot
and
zmoog
authored
Add OpenAPI 3.0 specification for Classeviva API with GitHub Pages publishing (#67)
* Initial plan * Add comprehensive OpenAPI specification for Classeviva API Co-authored-by: zmoog <[email protected]> * Add comprehensive documentation for OpenAPI specification Co-authored-by: zmoog <[email protected]> * Fix typo in OpenAPI spec and add clarification note Co-authored-by: zmoog <[email protected]> * Add GitHub Pages workflow to publish OpenAPI documentation Co-authored-by: zmoog <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: zmoog <[email protected]>
1 parent 5cfb7fa commit 3a0d7d5

4 files changed

Lines changed: 1754 additions & 0 deletions

File tree

‎.github/workflows/openapi-docs.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: OpenAPI Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'openapi.yaml'
9+
- '.github/workflows/openapi-docs.yml'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Setup Node
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: '20'
32+
33+
- name: Generate HTML documentation
34+
run: |
35+
# Install Redoc CLI
36+
npm install -g @redocly/cli
37+
38+
# Create output directory
39+
mkdir -p docs
40+
41+
# Generate standalone HTML file
42+
redocly build-docs openapi.yaml --output docs/index.html
43+
44+
# Create a simple redirect page at root
45+
cat > docs/404.html << 'EOF'
46+
<!DOCTYPE html>
47+
<html>
48+
<head>
49+
<meta charset="utf-8">
50+
<title>Redirecting...</title>
51+
<meta http-equiv="refresh" content="0; url=/classeviva/">
52+
</head>
53+
<body>
54+
Redirecting to documentation...
55+
</body>
56+
</html>
57+
EOF
58+
59+
- name: Setup Pages
60+
uses: actions/configure-pages@v4
61+
62+
- name: Upload artifact
63+
uses: actions/upload-pages-artifact@v3
64+
with:
65+
path: 'docs'
66+
67+
deploy:
68+
environment:
69+
name: github-pages
70+
url: ${{ steps.deployment.outputs.page_url }}
71+
runs-on: ubuntu-latest
72+
needs: build
73+
steps:
74+
- name: Deploy to GitHub Pages
75+
id: deployment
76+
uses: actions/deploy-pages@v4

‎OPENAPI.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# OpenAPI Specification
2+
3+
This directory contains the OpenAPI 3.0 specification for the Classeviva API.
4+
5+
## What is this?
6+
7+
The `openapi.yaml` file is a machine-readable API specification that describes all the endpoints, request/response formats, and data models for the Classeviva school portal API.
8+
9+
**Note**: This is an unofficial specification created by reverse engineering and community documentation. The official Classeviva API is not publicly documented by Spaggiari.
10+
11+
## What can I do with it?
12+
13+
### 1. View Interactive Documentation
14+
15+
#### Online (GitHub Pages)
16+
The API documentation is automatically published to GitHub Pages:
17+
18+
🔗 **https://zmoog.github.io/classeviva/**
19+
20+
This is updated automatically whenever the `openapi.yaml` file is changed on the `main` branch.
21+
22+
#### Using Swagger UI Online
23+
1. Go to https://editor.swagger.io/
24+
2. Click "File" → "Import File"
25+
3. Upload the `openapi.yaml` file
26+
4. Browse the interactive documentation
27+
28+
#### Using Redoc Locally
29+
```bash
30+
npx @redocly/cli preview-docs openapi.yaml
31+
```
32+
33+
Then open http://localhost:8080 in your browser.
34+
35+
### 2. Generate API Clients
36+
37+
Generate a client library in your preferred programming language:
38+
39+
#### Python
40+
```bash
41+
npx @openapitools/openapi-generator-cli generate \
42+
-i openapi.yaml \
43+
-g python \
44+
-o ./generated/python-client
45+
```
46+
47+
#### JavaScript/TypeScript
48+
```bash
49+
npx @openapitools/openapi-generator-cli generate \
50+
-i openapi.yaml \
51+
-g typescript-axios \
52+
-o ./generated/typescript-client
53+
```
54+
55+
#### Java
56+
```bash
57+
npx @openapitools/openapi-generator-cli generate \
58+
-i openapi.yaml \
59+
-g java \
60+
-o ./generated/java-client
61+
```
62+
63+
#### Other Languages
64+
OpenAPI Generator supports [50+ languages](https://openapi-generator.tech/docs/generators). Replace the `-g` flag with your target language.
65+
66+
### 3. Validate API Requests
67+
68+
Use the specification to validate API requests and responses in your tests:
69+
70+
```bash
71+
npm install -g @redocly/cli
72+
redocly lint openapi.yaml
73+
```
74+
75+
### 4. Mock API Server
76+
77+
Create a mock server for testing without hitting the real API:
78+
79+
```bash
80+
npx @stoplight/prism-cli mock openapi.yaml
81+
```
82+
83+
## API Overview
84+
85+
The Classeviva API provides access to:
86+
87+
- **Authentication**: Login and session management
88+
- **Grades**: Student grades and evaluations
89+
- **Agenda**: Homework, events, and assignments
90+
- **Noticeboard**: School announcements and circulars
91+
- **Absences**: Student absences and late arrivals
92+
- **Lessons**: Lesson records and topics
93+
- **Calendar**: School calendar
94+
- **Student Profile**: Personal information
95+
- **Subjects**: Course subjects and teachers
96+
- **Academic Periods**: Trimesters, semesters
97+
- **Notes**: Teacher notes and warnings
98+
- **Didactics**: Teaching materials
99+
- **Schoolbooks**: Required textbooks
100+
101+
## Authentication
102+
103+
All API requests require these headers:
104+
105+
```
106+
Z-Dev-Apikey: Tg1NWEwNGIgIC0K
107+
User-Agent: CVVS/std/4.2.3 Android/12
108+
Content-Type: application/json
109+
```
110+
111+
For authenticated endpoints, you also need:
112+
113+
```
114+
Z-Auth-Token: <token from login response>
115+
```
116+
117+
### Login Flow
118+
119+
1. Call `POST /auth/login` with credentials:
120+
```json
121+
{
122+
"uid": "username",
123+
"pass": "password",
124+
"ident": null
125+
}
126+
```
127+
128+
2. Extract the `token` and student `ident` from the response
129+
130+
3. Extract the numeric student ID from `ident` (e.g., "G9123456R" → "9123456")
131+
132+
4. Use the token in subsequent requests with the `Z-Auth-Token` header
133+
134+
5. Use the student ID in endpoint paths (e.g., `/students/{studentId}/grades`)
135+
136+
## Contributing
137+
138+
If you find any issues or want to add missing endpoints, please:
139+
140+
1. Check the unofficial documentation at [Classeviva-Official-Endpoints](https://github.com/Lioydiano/Classeviva-Official-Endpoints)
141+
2. Open an issue or pull request
142+
143+
## Resources
144+
145+
- [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.3)
146+
- [OpenAPI Generator](https://openapi-generator.tech/)
147+
- [Swagger Editor](https://editor.swagger.io/)
148+
- [Redocly CLI](https://redocly.com/docs/cli/)
149+
- [Unofficial API Documentation](https://github.com/Lioydiano/Classeviva-Official-Endpoints)

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,20 @@
22

33
Classeviva is a Go library and CLI tool to access the popular school portal https://web.spaggiari.eu.
44

5+
## OpenAPI Specification
6+
7+
📖 **[View Interactive API Documentation](https://zmoog.github.io/classeviva/)**
8+
9+
An [OpenAPI specification](openapi.yaml) is available that documents the Classeviva API endpoints. This specification can be used to:
10+
11+
- **View interactive API documentation** - Automatically published to [GitHub Pages](https://zmoog.github.io/classeviva/)
12+
- **Generate API clients** in your preferred programming language using tools like [OpenAPI Generator](https://openapi-generator.tech/)
13+
- **Understand API endpoints** and request/response formats
14+
15+
The specification is based on the unofficial community documentation at [Classeviva-Official-Endpoints](https://github.com/Lioydiano/Classeviva-Official-Endpoints).
16+
17+
**Note**: This is an unofficial specification as the Classeviva API is not publicly documented by Spaggiari.
18+
519
## Quick Start
620

721
### Install

0 commit comments

Comments
 (0)