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 package at.mocode.gateway.routing
import at.mocode.dto.base.ApiResponse import at.mocode.dto.base.ApiResponse
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.* import io.ktor.server.response.*
import io.ktor.server.routing.* import io.ktor.server.routing.*
import kotlinx.serialization.Serializable import kotlinx.serialization.Serializable
import java.io.File
/** /**
* Sets up routes for API documentation * 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 ```yaml
/api/horses/advanced-search: /api/horses/advanced-search:
get: get:
tags: tags:
- Horse Registry - Horse Registry
summary: Advanced Horse Search summary: Advanced Horse Search
description: | description: |
Searches for horses using multiple optional criteria. Searches for horses using multiple optional criteria.
Returns a list of horses matching the specified criteria. Returns a list of horses matching the specified criteria.
If no criteria are provided, returns all horses (subject to pagination). If no criteria are provided, returns all horses (subject to pagination).
operationId: advancedSearchHorses operationId: advancedSearchHorses
parameters: parameters:
- name: name - name: name
in: query in: query
description: Full or partial horse name to search for description: Full or partial horse name to search for
required: false required: false
schema: schema:
type: string type: string
example: "Maestoso" example: "Maestoso"
- name: breed - name: breed
in: query in: query
description: Horse breed description: Horse breed
required: false required: false
schema: schema:
type: string type: string
example: "Lipizzaner" example: "Lipizzaner"
- name: minAge - name: minAge
in: query in: query
description: Minimum age in years description: Minimum age in years
required: false required: false
schema: schema:
type: integer type: integer
format: int32 format: int32
minimum: 0 minimum: 0
example: 3 example: "3"
- name: maxAge - name: maxAge
in: query in: query
description: Maximum age in years description: Maximum age in years
required: false required: false
schema: schema:
type: integer type: integer
format: int32 format: int32
minimum: 0 minimum: 0
example: 15 example: "15"
- name: gender - name: gender
in: query in: query
description: Horse gender description: Horse gender
required: false required: false
schema: schema:
type: string type: string
enum: [STALLION, MARE, GELDING] enum: [ STALLION, MARE, GELDING ]
example: "MARE" example: "MARE"
- name: ownerName - name: ownerName
in: query in: query
description: Full or partial name of the horse's owner description: Full or partial name of the horse's owner
required: false required: false
schema: schema:
type: string type: string
example: "Schmidt" example: "Schmidt"
security: security:
- bearerAuth: [] - bearerAuth: [ ]
responses: responses:
'200': '200':
description: Successful operation description: Successful operation
content: content:
application/json: application/json:
schema: schema:
type: object type: object
properties: properties:
success: success:
type: boolean type: boolean
example: true example: true
data: data:
type: array type: array
items: items:
$ref: '#/components/schemas/HorseResponse' $ref: '#/components/schemas/HorseResponse'
message: message:
type: string type: string
example: "Horses retrieved successfully" example: "Horses retrieved successfully"
timestamp: timestamp:
type: string type: string
format: date-time format: date-time
example: "2024-07-21T13:35:00Z" example: "2024-07-21T13:35:00Z"
example: example:
success: true success: true
data: [ data: [
{ {
"id": "550e8400-e29b-41d4-a716-446655440000", "id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Maestoso Mara", "name": "Maestoso Mara",
"birthYear": 2015, "birthYear": 2015,
"breed": "Lipizzaner", "breed": "Lipizzaner",
"color": "Grey", "color": "Grey",
"gender": "MARE", "gender": "MARE",
"feiRegistered": true, "feiRegistered": true,
"ownerId": "550e8400-e29b-41d4-a716-446655440001", "ownerId": "550e8400-e29b-41d4-a716-446655440001",
"active": true "active": true
}, },
{ {
"id": "550e8400-e29b-41d4-a716-446655440002", "id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Maestoso Belvedere", "name": "Maestoso Belvedere",
"birthYear": 2018, "birthYear": 2018,
"breed": "Lipizzaner", "breed": "Lipizzaner",
"color": "Grey", "color": "Grey",
"gender": "STALLION", "gender": "STALLION",
"feiRegistered": false, "feiRegistered": false,
"ownerId": "550e8400-e29b-41d4-a716-446655440001", "ownerId": "550e8400-e29b-41d4-a716-446655440001",
"active": true "active": true
} }
] ]
message: "Horses retrieved successfully" message: "Horses retrieved successfully"
timestamp: "2024-07-21T13:35:00Z" timestamp: "2024-07-21T13:35:00Z"
'400': '400':
description: Invalid parameters description: Invalid parameters
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/ErrorResponse' $ref: '#/components/schemas/ErrorResponse'
'401': '401':
description: Unauthorized - Authentication required description: Unauthorized - Authentication required
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/ErrorResponse' $ref: '#/components/schemas/ErrorResponse'
'403': '403':
description: Forbidden - Insufficient permissions description: Forbidden - Insufficient permissions
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/ErrorResponse' $ref: '#/components/schemas/ErrorResponse'
``` ```
## Step 3: Generate and Validate Documentation ## Step 3: Generate and Validate Documentation