feat(jans-config-api): We are having some issues with the generated swagger yml files

# Description
The generated yml files have some gap and inconsistencies which is impacting API usage for consumers like AdminUI.
Below is the analysis report for refrence.

# OpenAPI Specification Compliance Analysis Report

**Project:** Janssen Admin UI - Config API
**Analyzed File:** `configApiSpecs.yaml` (23,698 lines)
**Analysis Date:** 2025-11-11
**OpenAPI Version:** 3.0.3
**Overall Compliance Score:** 78%

---

## Executive Summary

This report provides a comprehensive analysis of the OpenAPI specifications used to generate the Orval client for the Janssen Admin UI project. The specifications are created by merging 9 source YAML files from the JanssenProject repository into a single `configApiSpecs.yaml` file.

### Specification Overview

| Metric | Value |
|--------|-------|
| Total Lines | 23,698 |
| Source Files | 9 YAML files |
| API Paths | 87 |
| Total Operations | 214 |
| HTTP Methods | GET (105), POST (30), PUT (31), DELETE (24), PATCH (24) |
| Component Schemas | 122 |
| Tags Defined | 49 |
| Security Schemes | 1 (OAuth2 Client Credentials) |
| OAuth Scopes | 73 |

### Source Files

1. `jans-config-api-swagger.yaml` - Core configuration API
2. `fido2-plugin-swagger.yaml` - FIDO2 authentication
3. `user-mgt-plugin-swagger.yaml` - User management
4. `jans-admin-ui-plugin-swagger.yaml` - Admin UI features
5. `jans-link-plugin-swagger.yaml` - Jans Link configuration
6. `scim-plugin-swagger.yaml` - SCIM configuration
7. `kc-saml-plugin-swagger.yaml` - SAML operations
8. `kc-link-plugin-swagger.yaml` - Keycloak Link
9. `lock-plugin-swagger.yaml` - Lock service configuration

### Compliance Breakdown

| Category | Score | Status |
|----------|-------|--------|
| Required Fields | 95% | ⚠️ Version placeholder |
| Schema Structure | 88% | ⚠️ Arrays without items |
| Response Definitions | 65% | ❌ Missing error schemas |
| Security | 90% | ⚠️ Placeholder URL |
| Documentation | 70% | ⚠️ Missing descriptions |
| Path Design | 85% | ⚠️ Verbs in paths |
| Naming Conventions | 100% | ✅ Perfect |

---

## 🔴 CRITICAL ISSUES (Must Fix - Breaks Code Generation)

These issues violate OpenAPI 3.0 specification requirements and will cause failures or incorrect behavior in code generators.

### 1. Arrays Without Items Definition ❌

**Severity:** CRITICAL
**OpenAPI Violation:** Arrays MUST have `items` defined per OpenAPI 3.0 spec
**Count:** 15 instances

**Affected Lines:**
- Line 104, 812, 964, 997
- Line 1608, 1758, 1801, 1905
- Line 2047, 2170, 2292, 2428
- Line 3920, 4097, 4635

**Problem:**
```yaml
# ❌ WRONG - Missing items definition
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
```

**Solution:**
```yaml
# ✅ CORRECT - Items defined
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/YourSchemaName'
```

**Impact:**
- Code generators cannot determine array element type
- TypeScript generators produce `any[]` instead of typed arrays
- Runtime type safety is compromised

---

### 2. Path Parameters Not in URL Paths ❌

**Severity:** CRITICAL
**OpenAPI Violation:** Path parameters must appear in the URL path with `{paramName}` syntax

**Affected Endpoints:**

| Line | Path | Invalid Parameter(s) |
|------|------|---------------------|
| 214 | `/api/v1/acrs` | `name` |
| 593 | `/api/v1/agama-repo` | `qname`, `inum`, `name` |
| 984 | `/api/v1/jans-assets/asset-type` | `service-name` |
| 1176 | `/api/v1/attributes` | `inum` |

**Problem:**
```yaml
# ❌ WRONG - Parameter 'inum' not in path
paths:
/api/v1/attributes:
get:
parameters:
- name: inum
in: path
required: true
schema:
type: string
```

**Solution:**
These should be **query parameters**, not path parameters:
```yaml
# ✅ CORRECT - Query parameter
paths:
/api/v1/attributes:
get:
parameters:
- name: inum
in: query
required: false
schema:
type: string
```

**Impact:**
- Code generation fails or produces incorrect code
- API calls will fail at runtime
- Client libraries cannot construct valid URLs

---

### 3. 401 Unauthorized Responses Missing Schemas ❌

**Severity:** CRITICAL
**Statistics:** 205 out of 207 (99%) lack error schemas
**OpenAPI Best Practice Violation:** Error responses should include structured error details

**Problem:**
```yaml
# ❌ WRONG - No schema for error response
responses:
'401':
description: Unauthorized
```

**Solution:**
```yaml
# ✅ CORRECT - Error schema provided
responses:
'401':
description: Unauthorized - Invalid or missing authentication credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
```

**Impact:**
- Clients cannot programmatically handle authentication errors
- No structured error information (error codes, messages, etc.)
- Poor developer experience when debugging auth issues
- Generated client code has weak error handling

---

### 4. 500 Internal Server Error Responses Missing Schemas ❌

**Severity:** CRITICAL
**Statistics:** 159 out of 214 (74%) lack error schemas
**OpenAPI Best Practice Violation:** Server error responses should return error details

**Problem:**
```yaml
# ❌ WRONG - No schema
responses:
'500':
description: Internal Server Error
```

**Solution:**
```yaml
# ✅ CORRECT - Error schema with details
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
```

**Recommended ApiError Schema:**
```yaml
components:
schemas:
ApiError:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
example: "AUTH_INVALID_TOKEN"
message:
type: string
description: Human-readable error message
example: "The provided authentication token is invalid or expired"
details:
type: object
additionalProperties: true
description: Additional error context
timestamp:
type: string
format: date-time
description: When the error occurred
path:
type: string
description: API path that generated the error
```

**Impact:**
- Difficult to debug production issues
- No standard error handling in generated clients
- Cannot track error patterns or types

---

## 🟡 MAJOR ISSUES (Should Fix - Standards Violations)

These issues violate OpenAPI best practices and significantly impact API quality, documentation, and usability.

### 5. All 49 Tags Missing Descriptions ⚠️

**Severity:** MAJOR
**OpenAPI Best Practice:** Tag descriptions are HIGHLY RECOMMENDED
**Location:** Lines 15-63

**Problem:**
```yaml
# ❌ WRONG - No descriptions
tags:
- name: Attribute
- name: Default Authentication Method
- name: Cache Configuration
- name: ACRS
- name: Agama
```

**Solution:**
```yaml
# ✅ CORRECT - Descriptive tags
tags:
- name: Attribute
description: |
Manage LDAP attributes, custom attributes, and attribute metadata.
Use these endpoints to create, update, delete, and query user/client attributes.

- name: Default Authentication Method
description: |
Configure and manage default authentication methods for the authorization server.
Controls how users authenticate (password, OTP, biometric, etc.).

- name: Cache Configuration
description: |
Configure caching layer settings including cache providers (Redis, Memcached, in-memory),
TTL values, and cache invalidation strategies.

- name: ACRS
description: |
Manage Authentication Context Class References (ACRS) that define authentication
strength levels and methods available in the system.

- name: Agama
description: |
Configure Agama authentication framework settings, flows, and deployment options.
```

**Impact:**
- **Generated documentation is unclear** - users don't understand endpoint groupings
- Poor API discoverability
- Developers must guess which endpoints to use for specific tasks
- No guidance on the purpose or scope of each tag group
- Impacts Swagger UI, ReDoc, and other documentation tools

**This addresses the "lack of endpoint grouping" issue mentioned in requirements!**

---

### 6. Success Responses (2xx) Missing Schemas ⚠️

**Severity:** MAJOR
**Count:** 29 instances
**OpenAPI Violation:** Success responses (except 204 No Content) should define response schemas

**Examples:**

| Line | Method | Path | Response Code | Issue |
|------|--------|------|---------------|-------|
| 317 | POST | (endpoint) | 201 Created | No schema |
| 389 | DELETE | (endpoint) | 204 No Content | OK (204 should have no content) |
| 497 | PUT | (endpoint) | 200 OK | No schema |

**Problem:**
```yaml
# ❌ WRONG - 200 response without schema
responses:
'200':
description: Success
```

**Solution:**
```yaml
# ✅ CORRECT - Schema defined
responses:
'200':
description: Successfully retrieved resource
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceResponse'
example:
id: "12345"
name: "Example Resource"
```

**Note:** 204 No Content responses correctly have no schema (this is expected).

**Impact:**
- Clients don't know what data structure to expect
- Cannot generate proper TypeScript interfaces
- No type safety in generated client code

---

### 7. OAuth2 Token URL Contains Placeholder ⚠️

**Severity:** MAJOR
**Location:** Line 23632
**OpenAPI Issue:** Non-functional security configuration

**Problem:**
```yaml
# ❌ WRONG - Placeholder URL
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: 'https://{op-hostname}/.../token'
scopes:
# ... scopes
```

**Solution Option 1 - Server Variables:**
```yaml
# ✅ CORRECT - Use server variables
servers:
- url: 'https://{hostname}'
variables:
hostname:
default: jans.local.io
description: OAuth provider hostname

securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: 'https://{hostname}/jans-auth/restv1/token'
scopes:
# ... scopes
```

**Solution Option 2 - Environment-specific:**
```yaml
# ✅ CORRECT - Document as configuration requirement
securitySchemes:
oauth2:
type: oauth2
description: |
OAuth2 client credentials flow. Configure tokenUrl with your OAuth provider.
Default: https://jans.local.io/jans-auth/restv1/token
flows:
clientCredentials:
tokenUrl: 'https://jans.local.io/jans-auth/restv1/token'
scopes:
# ... scopes
```

**Impact:**
- OAuth configuration requires manual code modification
- Cannot use generated client without changes
- Non-functional out-of-the-box

---

### 8. API Version is Placeholder ⚠️

**Severity:** MAJOR
**Location:** Line 10
**OpenAPI Required Field:** Version should use semantic versioning

**Problem:**
```yaml
# ❌ WRONG
info:
title: "Jans Config API"
version: "OAS Version"
```

**Solution:**
```yaml
# ✅ CORRECT
info:
title: "Jans Config API"
version: "1.0.0"
description: |
Comprehensive configuration API for Janssen Project identity and access
management platform. Provides endpoints for authentication, authorization,
user management, and system configuration.
```

**Versioning Strategy Recommendations:**
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Increment MAJOR for breaking changes
- Increment MINOR for new features (backward compatible)
- Increment PATCH for bug fixes
- Consider adding API versioning to paths (e.g., `/api/v1/`, `/api/v2/`)

**Impact:**
- Cannot track API version changes
- No versioning strategy for breaking changes
- Clients cannot specify compatible API versions

---

### 9. RESTful Path Design - Verbs in Paths ⚠️

**Severity:** MAJOR
**REST Anti-Pattern:** Paths should use nouns only; verbs belong in HTTP methods
**Count:** 6 violations

**Violations:**

| Line | Current Path (WRONG) | HTTP Method | Recommended Path (CORRECT) |
|------|---------------------|-------------|---------------------------|
| 13396 | `/api/v1/jans-auth-server/session/search` | POST | `/api/v1/jans-auth-server/sessions` |
| 13904 | `/api/v1/token/search` | POST | `/api/v1/tokens` |
| 16719 | `/admin-ui/license/retrieve` | GET | `/admin-ui/license` |
| 18453 | `/lock/audit/health/search` | POST | `/lock/audit/health` |
| 18498 | `/lock/audit/log/search` | POST | `/lock/audit/logs` |
| 18543 | `/lock/audit/telemetry/search` | POST | `/lock/audit/telemetry` |

**Example - Before:**
```yaml
# ❌ WRONG - Verb "search" in path
paths:
/api/v1/jans-auth-server/session/search:
post:
summary: Search sessions
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
```

**Example - After:**
```yaml
# ✅ CORRECT - Noun-based path with query parameters
paths:
/api/v1/jans-auth-server/sessions:
get:
summary: Search sessions
parameters:
- name: query
in: query
schema:
type: string
description: Search query string
- name: status
in: query
schema:
type: string
enum: [active, expired, terminated]
```

**For complex search (if POST is needed):**
```yaml
# ✅ ACCEPTABLE - POST to collection with search payload
paths:
/api/v1/jans-auth-server/sessions:
post:
summary: Advanced session search
description: Use POST for complex search criteria
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SessionSearchRequest'
```

**Impact:**
- Non-RESTful API design
- Confusing for API consumers
- Inconsistent with REST best practices
- Makes API harder to learn and use

---

### 10. 404 Not Found Responses Missing Schemas ⚠️

**Severity:** MAJOR
**Statistics:** 48 out of 70 (69%) lack schemas

**Problem:**
```yaml
# ❌ WRONG
responses:
'404':
description: Not Found
```

**Solution:**
```yaml
# ✅ CORRECT
responses:
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: "RESOURCE_NOT_FOUND"
message: "The requested attribute with ID 'abc123' was not found"
path: "/api/v1/attributes/abc123"
```

**Impact:**
- Cannot provide helpful "not found" error messages
- No guidance on why resource wasn't found
- Poor debugging experience

---

### 11. 400 Bad Request Responses Missing Schemas ⚠️

**Severity:** MAJOR
**Statistics:** 12 out of 62 (19%) lack schemas

**Problem:**
```yaml
# ❌ WRONG
responses:
'400':
description: Bad Request
```

**Solution:**
```yaml
# ✅ CORRECT - With validation details
responses:
'400':
description: Bad Request - Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
code: "VALIDATION_ERROR"
message: "Request validation failed"
details:
errors:
- field: "email"
message: "Invalid email format"
- field: "age"
message: "Must be greater than 0"
```

**Recommended ValidationError Schema:**
```yaml
components:
schemas:
ValidationError:
allOf:
- $ref: '#/components/schemas/ApiError'
- type: object
properties:
details:
type: object
properties:
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
```

**Impact:**
- Cannot explain validation failures
- Clients don't know which fields are invalid
- Poor form validation UX

---

## 🟢 MINOR ISSUES (Recommended Improvements)

These issues don't violate standards but following these recommendations will improve API quality and developer experience.

### 12. Tag Naming Inconsistencies ℹ️

**Severity:** MINOR
**Issue:** Inconsistent formatting and hierarchy markers

**Examples:**

| Current Tag Name | Issue |
|-----------------|-------|
| "Health - Check" | Uses hyphen separator |
| "Auth Server Health - Check" | Different format from "Health - Check" |
| "Configuration – Properties" | Uses en-dash (–) instead of hyphen (-) |
| "Admin UI - Role" | Inconsistent with "Admin UI - Permission" |
| "Admin UI - Role-Permissions Mapping" | Mixed hyphen usage |

**Recommendation:**
Standardize on one format:

```yaml
# ✅ CONSISTENT FORMAT
tags:
- name: Health Check
description: Basic system health endpoints

- name: Auth Server Health Check
description: Authentication server health monitoring

- name: Configuration - Properties
description: System configuration properties (use hyphen, not en-dash)

- name: Admin UI - Roles
description: Admin UI role management

- name: Admin UI - Permissions
description: Admin UI permission management

- name: Admin UI - Role Permissions
description: Admin UI role-to-permission mappings
```

---

### 13. Spelling Errors in Descriptions ℹ️

**Severity:** MINOR
**Count:** 16 typos found

**Errors Found:**

| Line(s) | Typo | Correction |
|---------|------|------------|
| 75 | "requied" | "required" |
| 882, 1226, 2670, 4350, 4962, 11735, 13440, 13948, 14173, 14933, 15124, 16865, 17845 | "seraching" | "searching" (13 occurrences) |
| 19155, 19158 | "extention" | "extension" (2 occurrences) |

**Impact:**
- Unprofessional documentation
- Confusing for non-native English speakers
- Affects generated documentation quality

**Recommendation:** Run spell-checker on all description fields.

---

### 14. Potentially Unused Schemas ℹ️

**Severity:** MINOR
**Count:** 24 schemas with minimal/no references

**Examples:**
- HealthStatus
- FacterData
- StatsData
- DeploymentDetails
- ProjectMetadata
- AttributeValidation
- PatchRequest
- LogPagedResult
- AuthenticationFilter
- AuthenticationProtectionConfiguration
- *(and 14 more)*

**Recommendation:**
1. Review each schema to determine if it's actually used
2. Remove unused schemas to reduce specification size
3. OR: Document if these are used by code generators or future endpoints

**Note:** Some may be intentionally included for code generation purposes.

---

### 15. No External Documentation Links ℹ️

**Severity:** MINOR
**OpenAPI Recommendation:** Use `externalDocs` for complex features

**Current State:** Zero `externalDocs` references found

**Recommendation:**
```yaml
# At API level
info:
title: "Jans Config API"
version: "1.0.0"
externalDocs:
description: Janssen Project Documentation
url: https://docs.jans.io

# At operation level
paths:
/api/v1/attributes:
get:
summary: Get all attributes
externalDocs:
description: Attribute Management Guide
url: https://docs.jans.io/admin/config-guide/attribute-management
```

**Benefits:**
- Links users to detailed documentation
- Provides context for complex operations
- Improves API discoverability

---

### 16. Missing Info Description Field ℹ️

**Severity:** MINOR
**OpenAPI Recommendation:** Include API-level description

**Current:**
```yaml
info:
title: "Jans Config API"
version: "OAS Version"
contact:
# ...
license:
# ...
# Missing description!
```

**Recommended:**
```yaml
info:
title: "Jans Config API"
version: "1.0.0"
description: |
# Janssen Configuration API

Comprehensive configuration API for the Janssen Project identity and access
management platform. This API provides endpoints for:

- **Authentication & Authorization**: Configure OAuth2, OIDC, SAML, and other auth protocols
- **User Management**: Manage users, groups, and attributes
- **System Configuration**: Configure cache, logging, database, and other system settings
- **FIDO2**: Configure FIDO2 authentication
- **Admin UI**: Manage admin UI roles, permissions, and settings

## Authentication

This API uses OAuth2 Client Credentials flow. Obtain a token from the
authorization server before making requests.

## Rate Limiting

Default rate limits: 100 requests per minute per client.

## Support

- Documentation: https://docs.jans.io
- Community: https://github.com/JanssenProject/jans/discussions
- Issues: https://github.com/JanssenProject/jans/issues
```

**Benefits:**
- Provides overview for new users
- Explains authentication requirements
- Links to support resources
- Improves generated documentation

---

### 17. Generic Contact and License Names ℹ️

**Severity:** MINOR
**Location:** Lines 5-9

**Current:**
```yaml
contact:
name: Contact
url: 'https://github.com/JanssenProject/...'
license:
name: License
url: 'https://github.com/JanssenProject/...'
```

**Recommended:**
```yaml
contact:
name: Janssen Project Team
email: support@jans.io
url: 'https://github.com/JanssenProject/jans'

license:
name: Apache License 2.0
url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
```

**Benefits:**
- Professional appearance
- Clear licensing information
- Proper contact information

---

### 18. Identical Summaries and Descriptions ℹ️

**Severity:** MINOR
**OpenAPI Best Practice:** Summary should be brief, description should be detailed

**Example Problem (Line 70):**
```yaml
# ❌ REDUNDANT
summary: "Returns application version"
description: "Returns application version"
```

**Recommended:**
```yaml
# ✅ DISTINCT AND INFORMATIVE
summary: "Get application version"
description: |
Returns the current version of the Janssen Config API application,
including build number and release date. Use this endpoint to verify
API version compatibility with your client.
```

**Benefits:**
- Better generated documentation
- More context for developers
- Clearer API understanding

---

### 19. JsonNode Schema Has No Properties ℹ️

**Severity:** MINOR
**Location:** Line 18959

**Current:**
```yaml
JsonNode:
type: object
```

**Issue:** Accepts any object structure (might be intentional for free-form JSON)

**If intentional:**
```yaml
JsonNode:
type: object
additionalProperties: true
description: Free-form JSON object with dynamic properties
```

**If specific structure is expected:**
```yaml
JsonNode:
type: object
description: JSON node representation
properties:
# Define expected properties
```

---

### 20. No Nullable Field Specifications ℹ️

**Severity:** MINOR
**Observation:** Zero fields marked as `nullable: true`

**OpenAPI 3.0 Support:**
```yaml
properties:
middleName:
type: string
nullable: true
description: User's middle name (optional, can be null)

lastLoginDate:
type: string
format: date-time
nullable: true
description: Last login timestamp (null if never logged in)
```

**Recommendation:**
- Review all optional fields
- Mark fields that can be null with `nullable: true`
- Improves type safety in generated clients

---

## 📊 Response Coverage Statistics

| Status Code | Total Occurrences | With Schema | Without Schema | Coverage |
|-------------|------------------|-------------|----------------|----------|
| 200 OK | 214 | 185 | 29 | 86% |
| 201 Created | ~30 | ~25 | ~5 | 83% |
| 204 No Content | ~24 | 0 | 24 | N/A (correct) |
| 400 Bad Request | 62 | 50 | 12 | 81% |
| 401 Unauthorized | 207 | 2 | 205 | **1%** ❌ |
| 404 Not Found | 70 | 22 | 48 | **31%** ⚠️ |
| 500 Internal Error | 214 | 55 | 159 | **26%** ❌ |

**Critical Gaps:**
- 401: Only 1% have schemas (need 99% more)
- 404: Only 31% have schemas (need 69% more)
- 500: Only 26% have schemas (need 74% more)

---
---

*End of Report*