Fix sdxStepTokenApi OpenAPI spec to pass CSIT governance linting

[rustyjux]

Description

Resolves all Spectral lint violations against the CSIT API Governance ruleset.

API changes

• Renamed POST /token → POST /tokens to satisfy the path-segments-no-verbs-probable rule (plural noun is correct REST convention for a resource endpoint)

New file: models.py

Extracted Pydantic models from routes.py and added OAS 3.1 / governance-compliant annotations:

• TokenRequest and TokenResponse — added description
• HealthResponse — new typed response model for GET /health (previously returned a raw dict)
• HTTPValidationError — replaced FastAPI's default schema with an RFC 7807 Problem Details structure (type, title, status, detail, errors with minItems: 1)
• ValidationError — restructured error item schema to match the style guide's required shape: type (string), location (enum: body | query | header | path | cookie), code, message

app.py

• Added summary and expanded description on the FastAPI() instance
• Annotated GET /health with operation_id, description, and a typed response_model
• Updated the RequestValidationError handler to return Problem Details format, mapping Pydantic error fields to location/code/message
• Added a custom_openapi() override for two purposes:
  1. Inject path item-level summary fields (/tokens, /health) — not natively supported by FastAPI route decorators
  2. Inject schema examples for all component schemas with explicit key ordering, bypassing the alphabetical sorting applied by FastAPI's schema pipeline

routes.py

• Added operation_id="createToken" and explicit responses descriptions for 200 and 422
• Imports TokenRequest, TokenResponse, HTTPValidationError from models.py

sdx-ca-token-api-spec.md, README.md, tests/test_routes.py

• Updated all references from /token to /tokens

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Documentation (non-breaking change with enhancements to documentation)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have checked that unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

Further comments

This took a few rounds working with an AI agent and probably would have been a pain to undertake manually. That said, adding

[rustyjux]

@ikethecoder attn breaking change, endpoint changed from /token --> /tokens

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud