openapi: 3.0.3 info: title: ${{ values.name }} API description: | REST API for the ${{ values.name }} microservice. This API provides endpoints for managing ${{ values.name }} resources. version: 1.0.0 contact: name: ${{ values.owner }} license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: http://localhost:8080 description: Local development server - url: https://${{ values.name }}.company.com description: Production server tags: - name: health description: Health check endpoints - name: resources description: Resource management endpoints paths: /health: get: tags: - health summary: Health check description: Returns the health status of the service operationId: getHealth responses: '200': description: Service is healthy content: application/json: schema: $ref: '#/components/schemas/HealthResponse' '503': description: Service is unhealthy content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /health/ready: get: tags: - health summary: Readiness check description: Returns whether the service is ready to accept traffic operationId: getReadiness responses: '200': description: Service is ready content: application/json: schema: $ref: '#/components/schemas/HealthResponse' '503': description: Service is not ready content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /health/live: get: tags: - health summary: Liveness check description: Returns whether the service is alive operationId: getLiveness responses: '200': description: Service is alive content: application/json: schema: $ref: '#/components/schemas/HealthResponse' /api/v1/resources: get: tags: - resources summary: List resources description: Returns a list of all resources operationId: listResources parameters: - name: page in: query description: Page number for pagination schema: type: integer default: 1 minimum: 1 - name: limit in: query description: Number of items per page schema: type: integer default: 20 minimum: 1 maximum: 100 - name: sort in: query description: Sort field and direction schema: type: string example: "created_at:desc" responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ResourceListResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: tags: - resources summary: Create resource description: Creates a new resource operationId: createResource requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateResourceRequest' responses: '201': description: Resource created successfully content: application/json: schema: $ref: '#/components/schemas/Resource' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Resource already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/v1/resources/{id}: get: tags: - resources summary: Get resource description: Returns a specific resource by ID operationId: getResource parameters: - name: id in: path required: true description: Resource ID schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Resource' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: tags: - resources summary: Update resource description: Updates an existing resource operationId: updateResource parameters: - name: id in: path required: true description: Resource ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateResourceRequest' responses: '200': description: Resource updated successfully content: application/json: schema: $ref: '#/components/schemas/Resource' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: - resources summary: Delete resource description: Deletes a specific resource operationId: deleteResource parameters: - name: id in: path required: true description: Resource ID schema: type: string format: uuid responses: '204': description: Resource deleted successfully '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: HealthResponse: type: object required: - status properties: status: type: string enum: [healthy, unhealthy] example: healthy timestamp: type: string format: date-time example: "2024-01-15T10:30:00Z" version: type: string example: "1.0.0" checks: type: object additionalProperties: type: object properties: status: type: string enum: [up, down] message: type: string Resource: type: object required: - id - name - created_at properties: id: type: string format: uuid example: "123e4567-e89b-12d3-a456-426614174000" name: type: string minLength: 1 maxLength: 255 example: "my-resource" description: type: string maxLength: 1000 example: "A sample resource" metadata: type: object additionalProperties: true created_at: type: string format: date-time example: "2024-01-15T10:30:00Z" updated_at: type: string format: date-time example: "2024-01-15T10:30:00Z" CreateResourceRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 255 example: "my-resource" description: type: string maxLength: 1000 example: "A sample resource" metadata: type: object additionalProperties: true UpdateResourceRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 example: "my-resource" description: type: string maxLength: 1000 example: "An updated resource" metadata: type: object additionalProperties: true ResourceListResponse: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/Resource' pagination: $ref: '#/components/schemas/Pagination' Pagination: type: object required: - page - limit - total properties: page: type: integer minimum: 1 example: 1 limit: type: integer minimum: 1 maximum: 100 example: 20 total: type: integer minimum: 0 example: 100 total_pages: type: integer minimum: 0 example: 5 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: "RESOURCE_NOT_FOUND" message: type: string example: "The requested resource was not found" details: type: object additionalProperties: true