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:48:36 +02:00
parent 81e40e70fc
commit 143de2b4d5
2 changed files with 127 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
api-gateway/src/jvmMain/kotlin/at/mocode/gateway/routing/DocRoutes.kt
-3
View File
@@ -1,12 +1,9 @@
package at.mocode.gateway.routing
import at.mocode.dto.base.ApiResponse
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.serialization.Serializable
import java.io.File
/**
* Sets up routes for API documentation
docs/API_DOCUMENTATION_EXAMPLE.md
+127 -127
View File
@@ -52,133 +52,133 @@ Following our API documentation guidelines, we would add the following to the Op
```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'
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