ce5ec9c158
Some checks failed
devportal-offline / build-offline (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
- Introduced InMemoryIssuerAuditSink to retain audit entries for testing. - Implemented InMemoryIssuerKeyRepository for deterministic key storage. - Created InMemoryIssuerRepository to manage issuer records in memory. - Added InMemoryIssuerTrustRepository for managing issuer trust overrides. - Each repository utilizes concurrent collections for thread-safe operations. - Enhanced deprecation tracking with a comprehensive YAML schema for API governance.
234 lines
7.1 KiB
YAML
234 lines
7.1 KiB
YAML
extends:
|
|
- "spectral:oas"
|
|
|
|
formats:
|
|
- "oas3"
|
|
|
|
rules:
|
|
stella-info-title:
|
|
description: "OpenAPI info.title must be present"
|
|
message: "Add a descriptive `info.title`"
|
|
given: "$.info.title"
|
|
severity: error
|
|
then:
|
|
function: truthy
|
|
|
|
stella-info-version:
|
|
description: "OpenAPI info.version must be present"
|
|
message: "Set `info.version` (SemVer or release tag)"
|
|
given: "$.info.version"
|
|
severity: error
|
|
then:
|
|
function: truthy
|
|
|
|
stella-servers-https:
|
|
description: "Servers should use https"
|
|
given: "$.servers[*].url"
|
|
severity: warn
|
|
then:
|
|
function: pattern
|
|
functionOptions:
|
|
match: "^https://"
|
|
|
|
operation-operationId-required:
|
|
description: "Every operation must have an operationId"
|
|
message: "Add an `operationId` for this operation"
|
|
given: "$.paths[*][*]"
|
|
severity: error
|
|
then:
|
|
field: operationId
|
|
function: truthy
|
|
|
|
stella-2xx-response-examples:
|
|
description: "Every 2xx response must include at least one example"
|
|
message: "Add an example or examples block to 2xx responses"
|
|
given: "$.paths[*][*].responses[?(@property.match(/^2\\d\\d$/))].content.*"
|
|
severity: error
|
|
then:
|
|
function: schema
|
|
functionOptions:
|
|
schema:
|
|
anyOf:
|
|
- required: [examples]
|
|
- required: [example]
|
|
|
|
stella-pagination-params:
|
|
description: "Collection GETs (list/search) must expose limit/cursor parameters"
|
|
message: "Add limit/cursor parameters for paged collection endpoints"
|
|
given: "$.paths[*][get]"
|
|
severity: warn
|
|
then:
|
|
function: schema
|
|
functionOptions:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
operationId:
|
|
type: string
|
|
allOf:
|
|
- if:
|
|
properties:
|
|
operationId:
|
|
pattern: "([Ll]ist|[Ss]earch|[Qq]uery)"
|
|
then:
|
|
required: [parameters]
|
|
properties:
|
|
parameters:
|
|
type: array
|
|
allOf:
|
|
- contains:
|
|
anyOf:
|
|
- required: ['$ref']
|
|
properties:
|
|
$ref:
|
|
pattern: 'parameters/LimitParam$'
|
|
- required: [name, in]
|
|
properties:
|
|
name:
|
|
const: limit
|
|
in:
|
|
const: query
|
|
- contains:
|
|
anyOf:
|
|
- required: ['$ref']
|
|
properties:
|
|
$ref:
|
|
pattern: 'parameters/CursorParam$'
|
|
- required: [name, in]
|
|
properties:
|
|
name:
|
|
const: cursor
|
|
in:
|
|
const: query
|
|
|
|
stella-idempotency-header:
|
|
description: "State-changing operations returning 201/202 should accept Idempotency-Key headers"
|
|
message: "Add Idempotency-Key header parameter for idempotent submissions"
|
|
given: "$.paths[*][?(@property.match(/^(post|put|patch)$/))]"
|
|
severity: warn
|
|
then:
|
|
function: schema
|
|
functionOptions:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
responses:
|
|
type: object
|
|
parameters:
|
|
type: array
|
|
allOf:
|
|
- if:
|
|
properties:
|
|
responses:
|
|
type: object
|
|
anyOf:
|
|
- required: ['201']
|
|
- required: ['202']
|
|
then:
|
|
required: [parameters]
|
|
properties:
|
|
parameters:
|
|
type: array
|
|
contains:
|
|
type: object
|
|
properties:
|
|
name:
|
|
const: Idempotency-Key
|
|
in:
|
|
const: header
|
|
required: [name, in]
|
|
|
|
stella-operationId-style:
|
|
description: "operationId must be lowerCamelCase"
|
|
given: "$.paths[*][*].operationId"
|
|
severity: warn
|
|
then:
|
|
function: casing
|
|
functionOptions:
|
|
type: camel
|
|
|
|
|
|
stella-jobs-idempotency-key:
|
|
description: "Orchestrator job submissions must accept Idempotency-Key header"
|
|
given: "$.paths['/jobs'].post.parameters"
|
|
severity: warn
|
|
then:
|
|
function: schema
|
|
functionOptions:
|
|
schema:
|
|
type: array
|
|
contains:
|
|
type: object
|
|
properties:
|
|
name:
|
|
const: Idempotency-Key
|
|
in:
|
|
const: header
|
|
required: [name, in]
|
|
|
|
# --- Deprecation Metadata Rules (per APIGOV-63-001) ---
|
|
|
|
stella-deprecated-has-metadata:
|
|
description: "Deprecated operations must have x-deprecation extension with required fields"
|
|
message: "Add x-deprecation metadata (deprecatedAt, sunsetAt, successorPath, reason) to deprecated operations"
|
|
given: "$.paths[*][*][?(@.deprecated == true)]"
|
|
severity: error
|
|
then:
|
|
field: x-deprecation
|
|
function: schema
|
|
functionOptions:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- deprecatedAt
|
|
- sunsetAt
|
|
- successorPath
|
|
- reason
|
|
properties:
|
|
deprecatedAt:
|
|
type: string
|
|
format: date-time
|
|
sunsetAt:
|
|
type: string
|
|
format: date-time
|
|
successorPath:
|
|
type: string
|
|
successorOperationId:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
migrationGuide:
|
|
type: string
|
|
format: uri
|
|
notificationChannels:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [slack, teams, email, webhook]
|
|
|
|
stella-deprecated-sunset-future:
|
|
description: "Sunset dates should be in the future (warn if sunset already passed)"
|
|
message: "x-deprecation.sunsetAt should be a future date"
|
|
given: "$.paths[*][*].x-deprecation.sunsetAt"
|
|
severity: warn
|
|
then:
|
|
function: truthy
|
|
|
|
stella-deprecated-migration-guide:
|
|
description: "Deprecated operations should include a migration guide URL"
|
|
message: "Consider adding x-deprecation.migrationGuide for consumer guidance"
|
|
given: "$.paths[*][*][?(@.deprecated == true)].x-deprecation"
|
|
severity: hint
|
|
then:
|
|
field: migrationGuide
|
|
function: truthy
|
|
|
|
stella-deprecated-notification-channels:
|
|
description: "Deprecated operations should specify notification channels"
|
|
message: "Add x-deprecation.notificationChannels to enable deprecation notifications"
|
|
given: "$.paths[*][*][?(@.deprecated == true)].x-deprecation"
|
|
severity: hint
|
|
then:
|
|
field: notificationChannels
|
|
function: truthy
|