mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

(fix) Umbau zu SCS

Browse Source 
### 1.1 OpenAPI-Dokumentation implementieren
- Swagger/OpenAPI in bestehenden Ktor-Diensten integrieren
- Zentrale API-Dokumentationsseite im API-Gateway erstellen
- CI/CD-Pipeline um automatische API-Dokumentationsgenerierung erweitern
- Entwickler-Guidelines für API-Dokumentation erstellen
This commit is contained in:
stefan
2025-07-21 13:45:58 +02:00
parent 77953c18f6
commit 81e40e70fc
13 changed files with 3192 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_DOCUMENTATION.md
+45 -17
View File
@@ -7,10 +7,10 @@ This document provides comprehensive documentation for the Meldestelle API Gatew
## Features Implemented
### ✅ OpenAPI/Swagger Integration
- **OpenAPI 3.0 specification** generation
- **OpenAPI 3.0 specification** using static YAML file
- **Swagger UI** interactive documentation
- **Automatic API documentation** from code annotations
- **Multiple server environments** (development, production)
- **Comprehensive API documentation** for all bounded contexts
- **Multiple server environments** (development, staging, production)
### ✅ Postman Collections
- **Comprehensive API collection** covering all endpoints
@@ -31,8 +31,11 @@ The API Gateway aggregates the following bounded contexts:
### 1. System Information
- `GET /` - API Gateway information
- `GET /health` - Health check for all contexts
- `GET /api` - API documentation overview
- `GET /docs` - Central API documentation page
- `GET /api` - Redirects to central API documentation page
- `GET /api/json` - API documentation overview in JSON format
- `GET /swagger` - Interactive Swagger UI
- `GET /openapi` - Raw OpenAPI specification
### 2. Authentication Context (`/auth/*`)
- `POST /auth/register` - User registration
@@ -62,6 +65,16 @@ The API Gateway aggregates the following bounded contexts:
- `DELETE /api/horses/batch` - Batch delete horses
- `GET /api/horses/stats` - Get horse statistics
### 5. Event Management Context (`/api/events/*`)
- `GET /api/events` - Get all events
- `GET /api/events/stats` - Get event statistics
- `POST /api/events` - Create event
- `GET /api/events/{id}` - Get event by ID
- `PUT /api/events/{id}` - Update event
- `DELETE /api/events/{id}` - Delete event
- `GET /api/events/search` - Search events
- `GET /api/events/organizer/{organizerId}` - Get events by organizer
## Getting Started
### 1. Start the API Gateway
@@ -199,23 +212,38 @@ The test suite covers:
4. **Add integration tests** for the new functionality
5. **Update this documentation**
### OpenAPI Annotations
### OpenAPI Documentation
Use OpenAPI annotations to enhance documentation:
The API documentation is maintained in a static OpenAPI YAML file:
```kotlin
@OpenAPITag(name = "Horses", description = "Horse registry operations")
fun Route.horseRoutes() {
route("/api/horses") {
@OpenAPIResponse("200", [OpenAPIContent(HorseDto::class)])
@OpenAPIResponse("404", [OpenAPIContent(ErrorDto::class)])
get {
// Implementation
}
}
}
```yaml
# Location: api-gateway/src/jvmMain/resources/openapi/documentation.yaml
paths:
/api/horses:
get:
tags:
- Horse Registry
summary: Get All Horses
description: Returns a list of all horses
operationId: getAllHorses
security:
- bearerAuth: []
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/HorsesResponse'
```
To update the API documentation:
1. Edit the `documentation.yaml` file in `api-gateway/src/jvmMain/resources/openapi/`
2. Follow the OpenAPI 3.0.3 specification format
3. Restart the application to see changes in Swagger UI
## Configuration
### Environment Variables
docs/API_DOCUMENTATION_EXAMPLE.md
+221
View File
@@ -0,0 +1,221 @@
# API Documentation Example
This document demonstrates how to apply the API documentation guidelines to a new endpoint. It serves as a practical example for developers to follow when documenting their own API endpoints.
## Example Scenario
Let's say we're adding a new endpoint to the Horse Registry context that allows users to search for horses by multiple criteria.
## Step 1: Implement the API Endpoint
First, we would implement the endpoint in the appropriate route file:
```kotlin
// In HorseRoutes.kt
route("/api/horses") {
// Other endpoints...
// Advanced search endpoint
get("/advanced-search") {
// Parameter validation
val name = call.request.queryParameters["name"]
val breed = call.request.queryParameters["breed"]
val minAge = call.request.queryParameters["minAge"]?.toIntOrNull()
val maxAge = call.request.queryParameters["maxAge"]?.toIntOrNull()
val gender = call.request.queryParameters["gender"]
val ownerName = call.request.queryParameters["ownerName"]
// Call service to perform search
val horses = horseService.advancedSearch(
name = name,
breed = breed,
minAge = minAge,
maxAge = maxAge,
gender = gender,
ownerName = ownerName
)
// Return response
call.respond(
ApiResponse.success(
data = horses,
message = "Horses retrieved successfully"
)
)
}
}
```
## Step 2: Document the Endpoint in OpenAPI Specification
Following our API documentation guidelines, we would add the following to the OpenAPI specification file (`documentation.yaml`):
```yaml
/api/horses/advanced-search:
get:
tags:
- Horse Registry
summary: Advanced Horse Search
description: |
Searches for horses using multiple optional criteria.
Returns a list of horses matching the specified criteria.
If no criteria are provided, returns all horses (subject to pagination).
operationId: advancedSearchHorses
parameters:
- name: name
in: query
description: Full or partial horse name to search for
required: false
schema:
type: string
example: "Maestoso"
- name: breed
in: query
description: Horse breed
required: false
schema:
type: string
example: "Lipizzaner"
- name: minAge
in: query
description: Minimum age in years
required: false
schema:
type: integer
format: int32
minimum: 0
example: 3
- name: maxAge
in: query
description: Maximum age in years
required: false
schema:
type: integer
format: int32
minimum: 0
example: 15
- name: gender
in: query
description: Horse gender
required: false
schema:
type: string
enum: [STALLION, MARE, GELDING]
example: "MARE"
- name: ownerName
in: query
description: Full or partial name of the horse's owner
required: false
schema:
type: string
example: "Schmidt"
security:
- bearerAuth: []
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/HorseResponse'
message:
type: string
example: "Horses retrieved successfully"
timestamp:
type: string
format: date-time
example: "2024-07-21T13:35:00Z"
example:
success: true
data: [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Maestoso Mara",
"birthYear": 2015,
"breed": "Lipizzaner",
"color": "Grey",
"gender": "MARE",
"feiRegistered": true,
"ownerId": "550e8400-e29b-41d4-a716-446655440001",
"active": true
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Maestoso Belvedere",
"birthYear": 2018,
"breed": "Lipizzaner",
"color": "Grey",
"gender": "STALLION",
"feiRegistered": false,
"ownerId": "550e8400-e29b-41d4-a716-446655440001",
"active": true
}
]
message: "Horses retrieved successfully"
timestamp: "2024-07-21T13:35:00Z"
'400':
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
```
## Step 3: Generate and Validate Documentation
After updating the OpenAPI specification, we would generate and validate the documentation:
```bash
# Generate API documentation
./gradlew :api-gateway:generateApiDocs
# Validate OpenAPI specification
./gradlew :api-gateway:validateOpenApi
```
## Step 4: Test the Documentation
Finally, we would test the documentation by:
1. Starting the API Gateway:
```bash
./gradlew :api-gateway:run
```
2. Accessing Swagger UI at `http://localhost:8080/swagger`
3. Testing the new endpoint through the Swagger UI interface
4. Verifying that the documentation accurately represents the API behavior
## Summary
This example demonstrates how to apply the API documentation guidelines to a new endpoint. By following these steps, we ensure that:
1. The endpoint is well-documented with clear descriptions
2. All parameters are properly documented with types and examples
3. All possible responses are documented with status codes and examples
4. The documentation is validated and tested
5. The documentation is consistent with the rest of the API
This approach makes it easier for other developers, testers, and API consumers to understand and use the API.
docs/API_DOCUMENTATION_GUIDELINES.md
+304
View File
@@ -0,0 +1,304 @@
# API Documentation Guidelines
## Overview
This document provides guidelines for documenting APIs in the Meldestelle project. Following these guidelines ensures consistency across all API documentation and makes it easier for developers, testers, and API consumers to understand and use our APIs.
## Table of Contents
1. [Documentation Approach](#documentation-approach)
2. [OpenAPI Specification](#openapi-specification)
3. [Endpoint Documentation Standards](#endpoint-documentation-standards)
4. [Schema Documentation Standards](#schema-documentation-standards)
5. [Examples](#examples)
6. [Documentation Workflow](#documentation-workflow)
7. [Testing Documentation](#testing-documentation)
8. [Tools and Resources](#tools-and-resources)
## Documentation Approach
The Meldestelle project uses a **static OpenAPI YAML file** for API documentation. This means:
- API documentation is maintained in a dedicated YAML file, not generated from code annotations
- Developers must manually update the documentation when adding or modifying endpoints
- The documentation is served via Swagger UI and as static HTML
### Key Files
- **OpenAPI Specification**: `/api-gateway/src/jvmMain/resources/openapi/documentation.yaml`
- **OpenAPI Configuration**: `/api-gateway/src/jvmMain/kotlin/at/mocode/gateway/config/OpenApiConfig.kt`
- **Documentation Routes**: `/api-gateway/src/jvmMain/kotlin/at/mocode/gateway/routing/DocRoutes.kt`
- **Static HTML Documentation**: `/api-gateway/src/jvmMain/resources/static/docs/index.html`
## OpenAPI Specification
We use OpenAPI 3.0.3 for our API documentation. The specification is maintained in a YAML file at:
`/api-gateway/src/jvmMain/resources/openapi/documentation.yaml`
### Structure
The OpenAPI specification file is structured as follows:
```yaml
openapi: 3.0.3
info:
title: Meldestelle API
description: |
Self-Contained Systems API Gateway for Austrian Equestrian Federation.
version: 1.0.0
# Additional info fields...
servers:
# Server configurations...
tags:
# API tags for grouping endpoints...
paths:
# API endpoints...
components:
schemas:
# Data models...
securitySchemes:
# Security definitions...
```
## Endpoint Documentation Standards
When documenting a new API endpoint, include the following information:
### Required Elements
1. **Path and HTTP Method**: Define the endpoint path and HTTP method (GET, POST, PUT, DELETE)
2. **Tags**: Assign at least one tag to categorize the endpoint (e.g., Authentication, Master Data)
3. **Summary**: A brief one-line description of the endpoint
4. **Description**: A more detailed explanation of what the endpoint does
5. **Operation ID**: A unique identifier for the operation (camelCase)
6. **Responses**: Document all possible response status codes and their content
7. **Security**: Specify authentication requirements if applicable
### Optional Elements (Recommended)
1. **Request Body**: For POST/PUT methods, document the expected request body
2. **Parameters**: Document path, query, and header parameters
3. **Examples**: Provide example requests and responses
### Example Endpoint Documentation
```yaml
/auth/login:
post:
tags:
- Authentication
summary: User Login
description: Authenticates a user and returns a JWT token
operationId: login
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
example:
username: "user@example.com"
password: "SecurePassword123!"
responses:
'200':
description: Successful login
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
example:
success: true
data:
token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
userId: "550e8400-e29b-41d4-a716-446655440000"
personId: "550e8400-e29b-41d4-a716-446655440001"
username: "user@example.com"
email: "user@example.com"
message: "Login successful"
timestamp: "2024-07-21T13:35:00Z"
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
```
## Schema Documentation Standards
When documenting data models (schemas), include the following information:
### Required Elements
1. **Schema Name**: Use PascalCase for schema names (e.g., `LoginRequest`)
2. **Type**: Specify the type (usually `object` for complex types)
3. **Properties**: List all properties with their types and descriptions
4. **Required Properties**: Specify which properties are required
### Optional Elements (Recommended)
1. **Examples**: Provide example values for properties
2. **Format**: Specify formats for string types (e.g., `email`, `uuid`, `date-time`)
3. **Enums**: For properties with a fixed set of values, specify the allowed values
### Example Schema Documentation
```yaml
LoginRequest:
type: object
properties:
username:
type: string
description: The user's email address or username
format: email
example: "user@example.com"
password:
type: string
description: The user's password
format: password
example: "SecurePassword123!"
required:
- username
- password
```
## Examples
For a complete example of how to apply these guidelines to a new endpoint, see [API_DOCUMENTATION_EXAMPLE.md](API_DOCUMENTATION_EXAMPLE.md).
### Well-Documented Endpoint Example
Here's an example of a well-documented endpoint:
```yaml
/api/horses/{id}:
get:
tags:
- Horse Registry
summary: Get Horse by ID
description: |
Retrieves detailed information about a specific horse by its unique identifier.
Requires authentication and appropriate permissions.
operationId: getHorseById
parameters:
- name: id
in: path
description: Unique identifier of the horse
required: true
schema:
type: string
format: uuid
security:
- bearerAuth: []
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/HorseResponse'
example:
success: true
data:
id: "550e8400-e29b-41d4-a716-446655440000"
name: "Maestoso Mara"
birthYear: 2015
breed: "Lipizzaner"
color: "Grey"
gender: "STALLION"
feiRegistered: true
ownerId: "550e8400-e29b-41d4-a716-446655440001"
active: true
message: "Horse retrieved successfully"
timestamp: "2024-07-21T13:35:00Z"
'401':
description: Unauthorized - Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Horse not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
```
## Documentation Workflow
Follow these steps when adding or modifying API endpoints:
1. **Implement the API endpoint** in the appropriate controller/route file
2. **Update the OpenAPI specification** in `documentation.yaml`
3. **Generate the documentation** using the Gradle task:
```bash
./gradlew :api-gateway:generateApiDocs
```
4. **Validate the documentation** using the Gradle task:
```bash
./gradlew :api-gateway:validateOpenApi
```
5. **Test the documentation** by accessing the Swagger UI at `http://localhost:8080/swagger`
### CI/CD Pipeline
The project includes a CI/CD pipeline that automatically:
- Validates the OpenAPI specification
- Generates updated documentation
- Deploys the documentation to GitHub Pages
The workflow is defined in `.github/workflows/api-docs.yml` and is triggered:
- On changes to OpenAPI-related files
- On a weekly schedule
- Manually via GitHub Actions UI
## Testing Documentation
Always test your API documentation to ensure it accurately represents the API:
1. **Start the API Gateway**:
```bash
./gradlew :api-gateway:run
```
2. **Access Swagger UI**:
Open your browser and navigate to `http://localhost:8080/swagger`
3. **Test the documented endpoints**:
- Verify that all parameters are correctly documented
- Test example requests
- Verify that responses match the documentation
4. **Check static HTML documentation**:
Open your browser and navigate to `http://localhost:8080/docs`
## Tools and Resources
### Recommended Tools
- **Swagger Editor**: [https://editor.swagger.io/](https://editor.swagger.io/) - Online editor for OpenAPI specifications
- **OpenAPI Validator**: Built into our Gradle tasks (`validateOpenApi`)
- **Postman**: For testing APIs and generating collections
### Learning Resources
- [OpenAPI 3.0 Specification](https://spec.openapis.org/oas/v3.0.3)
- [Swagger UI Documentation](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)
- [OpenAPI Best Practices](https://oai.github.io/Documentation/best-practices.html)
## Conclusion
Following these guidelines ensures that our API documentation is consistent, comprehensive, and useful for all stakeholders. Good API documentation is a critical part of our development process and helps ensure the usability and maintainability of our APIs.
If you have questions or suggestions for improving these guidelines, please contact the API team.
docs/API_IMPLEMENTATION_SUMMARY.md
+60 -4
View File
@@ -23,7 +23,38 @@ This document summarizes the successful implementation of API documentation feat
- Added `configureOpenApi()` and `configureSwagger()` calls
- Swagger UI accessible at `/swagger` endpoint
### 2. Postman Collections
### 2. CI/CD Pipeline for Automatic API Documentation Generation
**Status: ✅ COMPLETED**
- **Added OpenAPI Generator plugin** to `api-gateway/build.gradle.kts`:
- Updated to latest version (7.3.0) for improved functionality
- Configured to generate HTML documentation from OpenAPI specification
- Created enhanced `generateApiDocs` Gradle task with error handling
- Added OpenAPI specification validation before generation
- Implemented documentation versioning based on project version
- Configured to copy all generated documentation assets, not just index.html
- **Enhanced GitHub Actions workflow** in `.github/workflows/api-docs.yml`:
- Updated to use latest GitHub Actions versions (checkout@v4, setup-java@v4)
- Added dedicated OpenAPI specification validation step
- Automatically triggers on changes to OpenAPI-related files
- Runs weekly on a schedule to ensure documentation is up-to-date
- Generates up-to-date API documentation
- Commits and pushes updated documentation to the repository
- Deploys documentation to GitHub Pages for better accessibility
- Includes notification steps for documentation updates
- Can be manually triggered via GitHub Actions UI
- **Benefits**:
- Documentation is always in sync with the API implementation
- No manual steps required to update documentation
- Changes to API are automatically reflected in the documentation
- Documentation is validated before generation to prevent errors
- Historical versions of documentation are preserved
- Documentation is accessible via GitHub Pages for better user experience
- Team is notified when documentation is updated
### 3. Postman Collections
**Status: ✅ COMPLETED**
- **Created comprehensive Postman collection** at `docs/postman/Meldestelle_API_Collection.json`:
@@ -70,8 +101,9 @@ This document summarizes the successful implementation of API documentation feat
5. `docs/API_IMPLEMENTATION_SUMMARY.md` - This summary document
### Files Modified:
1. `api-gateway/build.gradle.kts` - Added OpenAPI/Swagger dependencies
1. `api-gateway/build.gradle.kts` - Added OpenAPI/Swagger dependencies, OpenAPI Generator plugin, and enhanced documentation generation tasks
2. `api-gateway/src/main/kotlin/at/mocode/gateway/Application.kt` - Integrated OpenAPI configuration
3. `.github/workflows/api-docs.yml` - Enhanced CI/CD workflow for API documentation generation and deployment
## 🚀 How to Use
@@ -82,15 +114,38 @@ This document summarizes the successful implementation of API documentation feat
# Access Swagger UI
open http://localhost:8080/swagger
# Access static HTML documentation
open http://localhost:8080/docs
```
### 2. Postman Collection
### 2. Generate API Documentation Locally
```bash
# Generate API documentation
./gradlew :api-gateway:generateApiDocs
# Validate OpenAPI specification
./gradlew :api-gateway:validateOpenApi
```
### 3. Access Documentation on GitHub Pages
The API documentation is automatically deployed to GitHub Pages and can be accessed at:
```
https://{organization}.github.io/{repository}/
```
Different versions of the documentation are available at:
```
https://{organization}.github.io/{repository}/v{version}/
```
### 4. Postman Collection
1. Import `docs/postman/Meldestelle_API_Collection.json` into Postman
2. Set `baseUrl` variable to `http://localhost:8080`
3. Use the collection to test all API endpoints
4. Authentication tokens are automatically managed
### 3. API Tests
### 5. API Tests
```bash
# Run API tests (when compilation issues are resolved)
./gradlew :api-gateway:jvmTest
@@ -174,6 +229,7 @@ open http://localhost:8080/swagger
| Requirement | Status | Implementation |
|-------------|--------|----------------|
| **OpenAPI/Swagger Integration** | ✅ COMPLETED | Full OpenAPI 3.0 spec with Swagger UI |
| **CI/CD-Pipeline um automatische API-Dokumentationsgenerierung erweitern** | ✅ COMPLETED | GitHub Actions workflow with OpenAPI Generator |
| **Postman Collections erstellen** | ✅ COMPLETED | Comprehensive collection with 576 lines |
| **API-Tests schreiben** | ✅ COMPLETED | Integration test suite with 234 lines |
docs/SWAGGER_DOCUMENTATION.md
+174 -50
View File
@@ -23,60 +23,176 @@ Die Meldestelle API verfügt jetzt über eine vollständige Swagger/OpenAPI-Doku
## Dokumentierte Endpunkte
### Basis-Endpunkte
- `GET /` - API Gateway Information
- `GET /health` - Gesundheitsprüfung des Services
- `GET /api` - API-Informationen
- `GET /docs` - Zentrale API-Dokumentationsseite
- `GET /api` - Weiterleitung zur zentralen API-Dokumentationsseite
- `GET /api/json` - API-Informationen im JSON-Format
### Person Management (`/api/persons`)
- `GET /api/persons` - Alle Personen abrufen
- `POST /api/persons` - Neue Person erstellen
- `GET /api/persons/{id}` - Person nach UUID abrufen
- `PUT /api/persons/{id}` - Person aktualisieren
- `DELETE /api/persons/{id}` - Person löschen
- `GET /api/persons/oeps/{oepsSatzNr}` - Person nach OEPS-Nummer abrufen
- `GET /api/persons/search?q={query}` - Personen suchen
- `GET /api/persons/verein/{vereinId}` - Personen nach Verein-ID abrufen
### Authentication Context (`/auth/*`)
- `POST /auth/login` - Benutzeranmeldung
- `POST /auth/register` - Benutzerregistrierung
- `GET /auth/profile` - Benutzerprofil abrufen
### Master Data Context (`/api/masterdata/*`)
- `GET /api/masterdata/countries` - Alle Länder abrufen
- `POST /api/masterdata/countries` - Neues Land erstellen
- `GET /api/masterdata/countries/{id}` - Land nach ID abrufen
- `PUT /api/masterdata/countries/{id}` - Land aktualisieren
- `DELETE /api/masterdata/countries/{id}` - Land löschen
### Horse Registry Context (`/api/horses/*`)
- `GET /api/horses` - Alle Pferde abrufen
- `GET /api/horses/fei-registered` - FEI-registrierte Pferde abrufen
- `GET /api/horses/stats` - Pferdestatistiken abrufen
- `POST /api/horses/stats` - Neues Pferd registrieren
- `GET /api/horses/{id}` - Pferd nach ID abrufen
### Event Management Context (`/api/events/*`)
- `GET /api/events` - Alle Veranstaltungen abrufen
- `GET /api/events/stats` - Veranstaltungsstatistiken abrufen
- `POST /api/events/stats` - Neue Veranstaltung erstellen
## Schema-Definitionen
### Person
### LoginRequest
```yaml
Person:
LoginRequest:
type: object
properties:
email:
type: string
format: email
password:
type: string
format: password
required:
- email
- password
```
### UserProfileResponse
```yaml
UserProfileResponse:
type: object
properties:
id:
type: string
format: uuid
vorname:
type: string
nachname:
type: string
geburtsdatum:
type: string
format: date
oepsSatzNr:
type: string
vereinId:
type: string
format: uuid
email:
type: string
format: email
telefon:
firstName:
type: string
required:
- vorname
- nachname
lastName:
type: string
phoneNumber:
type: string
roles:
type: array
items:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
```
### Error
### CountryResponse
```yaml
Error:
CountryResponse:
type: object
properties:
error:
id:
type: string
required:
- error
format: uuid
name:
type: string
isoCode:
type: string
active:
type: boolean
```
### HorseResponse
```yaml
HorseResponse:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
birthYear:
type: integer
breed:
type: string
color:
type: string
gender:
type: string
enum: [STALLION, MARE, GELDING]
feiRegistered:
type: boolean
ownerId:
type: string
format: uuid
active:
type: boolean
```
### EventResponse
```yaml
EventResponse:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
startDate:
type: string
format: date
endDate:
type: string
format: date
location:
type: string
organizerId:
type: string
format: uuid
description:
type: string
status:
type: string
enum: [DRAFT, PUBLISHED, CANCELLED, COMPLETED]
```
### ErrorResponse
```yaml
ErrorResponse:
type: object
properties:
success:
type: boolean
message:
type: string
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
timestamp:
type: string
format: date-time
```
## Verwendung
@@ -101,25 +217,26 @@ Besuchen Sie `http://localhost:8080/openapi` um die vollständige OpenAPI-Spezif
### Neue Endpunkte hinzufügen
Um neue API-Endpunkte zu dokumentieren, erweitern Sie die Datei:
`server/src/main/resources/openapi.yaml`
`api-gateway/src/jvmMain/resources/openapi/documentation.yaml`
### Beispiel für neuen Endpunkt:
```yaml
/api/vereine:
/api/events/categories:
get:
summary: Get all clubs
description: Retrieve a list of all clubs
tags:
- Clubs
- Event Management
summary: Get Event Categories
description: Returns a list of all event categories
operationId: getEventCategories
responses:
'200':
description: List of clubs
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Verein'
$ref: '#/components/schemas/EventCategoryResponse'
```
## Technische Details
@@ -130,19 +247,26 @@ Um neue API-Endpunkte zu dokumentieren, erweitern Sie die Datei:
### Konfiguration
Die Swagger/OpenAPI-Konfiguration befindet sich in:
- `server/src/main/kotlin/at/mocode/plugins/Routing.kt`
- `server/src/main/resources/openapi.yaml`
- `api-gateway/src/jvmMain/kotlin/at/mocode/gateway/config/OpenApiConfig.kt` - Konfiguration der OpenAPI und Swagger UI Endpunkte
- `api-gateway/src/jvmMain/kotlin/at/mocode/gateway/module.kt` - Integration der OpenAPI-Konfiguration in die Anwendung
- `api-gateway/src/jvmMain/resources/openapi/documentation.yaml` - OpenAPI-Spezifikation im YAML-Format
### Tests
Automatisierte Tests für die Swagger-Funktionalität:
- `server/src/test/kotlin/at/mocode/SwaggerTest.kt`
### Implementierte Funktionen
- Vollständige OpenAPI 3.0.3 Spezifikation
- Interaktive Swagger UI für API-Exploration
- Dokumentation aller API-Endpunkte aus allen Bounded Contexts
- Authentifizierung mit JWT-Token
- Beispiel-Requests und -Responses für alle Endpunkte
- Schema-Definitionen für alle Datenmodelle
## Nächste Schritte
## Aktueller Status
1. **Erweitern Sie die Dokumentation** für weitere API-Endpunkte (Vereine, Turniere, etc.)
2. **Fügen Sie Authentifizierung hinzu** zur OpenAPI-Spezifikation wenn implementiert
3. **Konfigurieren Sie Produktions-URLs** in der OpenAPI-Spezifikation
4. **Implementieren Sie API-Versionierung** in der Dokumentation
✅ **Implementiert**:
- OpenAPI-Spezifikation für alle Bounded Contexts
- Swagger UI für interaktive API-Exploration
- JWT-Authentifizierung in der OpenAPI-Spezifikation
- Produktions- und Entwicklungs-URLs in der Spezifikation
- Vollständige Dokumentation aller Endpunkte und Datenmodelle
## Troubleshooting