222 lines
7.3 KiB
YAML
222 lines
7.3 KiB
YAML
rules:
|
|
# 基础结构错误
|
|
- id: MISSING_OPENAPI_VERSION
|
|
pattern: openapi
|
|
severity: critical
|
|
category: syntax
|
|
title: Missing OpenAPI Version
|
|
description: OpenAPI document must specify the OpenAPI version.
|
|
suggestions:
|
|
- description: Add openapi field with version 3.0.x or 3.1.x
|
|
codeExample: '"openapi": "3.0.3"'
|
|
documentationUrl: https://spec.openapis.org/oas/v3.0.3/#openapi-object
|
|
|
|
- id: INVALID_OPENAPI_VERSION
|
|
pattern: openapi
|
|
severity: error
|
|
category: compatibility
|
|
title: Invalid OpenAPI Version
|
|
description: OpenAPI version should be 3.0.x or 3.1.x for proper support.
|
|
suggestions:
|
|
- description: Use a supported OpenAPI version
|
|
codeExample: '"openapi": "3.0.3"'
|
|
|
|
# Info 对象错误
|
|
- id: MISSING_INFO_TITLE
|
|
pattern: info.title
|
|
severity: error
|
|
category: validation
|
|
title: Missing API Title
|
|
description: API title is required in the info object.
|
|
suggestions:
|
|
- description: Add a descriptive title for your API
|
|
codeExample: '"title": "My API"'
|
|
|
|
- id: MISSING_INFO_VERSION
|
|
pattern: info.version
|
|
severity: error
|
|
category: validation
|
|
title: Missing API Version
|
|
description: API version is required in the info object.
|
|
suggestions:
|
|
- description: Add a version number using semantic versioning
|
|
codeExample: '"version": "1.0.0"'
|
|
documentationUrl: https://semver.org/
|
|
|
|
# Paths 错误
|
|
- id: EMPTY_PATHS
|
|
pattern: paths
|
|
severity: error
|
|
category: validation
|
|
title: Empty Paths Object
|
|
description: OpenAPI document must contain at least one path.
|
|
suggestions:
|
|
- description: Add at least one API endpoint
|
|
codeExample: '"/users": { "get": { "responses": { "200": { "description": "Success" } } } }'
|
|
|
|
- id: INVALID_PATH_FORMAT
|
|
pattern: paths.*
|
|
severity: error
|
|
category: syntax
|
|
title: Invalid Path Format
|
|
description: Path must start with a forward slash.
|
|
suggestions:
|
|
- description: Ensure path starts with /
|
|
codeExample: '"/users" instead of "users"'
|
|
|
|
- id: MISSING_OPERATION_RESPONSES
|
|
pattern: paths.*.*.responses
|
|
severity: error
|
|
category: validation
|
|
title: Missing Operation Responses
|
|
description: Every operation must define at least one response.
|
|
suggestions:
|
|
- description: Add at least a default response
|
|
codeExample: '"responses": { "200": { "description": "Success" } }'
|
|
|
|
# 参数错误
|
|
- id: PATH_PARAMETER_NOT_REQUIRED
|
|
pattern: paths.*.*.parameters.*
|
|
severity: error
|
|
category: validation
|
|
title: Path Parameter Not Required
|
|
description: Path parameters must be marked as required.
|
|
suggestions:
|
|
- description: Set required: true for path parameters
|
|
codeExample: '"required": true'
|
|
|
|
- id: MISSING_PARAMETER_NAME
|
|
pattern: paths.*.*.parameters.*.name
|
|
severity: error
|
|
category: validation
|
|
title: Missing Parameter Name
|
|
description: Parameter must have a name.
|
|
suggestions:
|
|
- description: Add a name for the parameter
|
|
codeExample: '"name": "userId"'
|
|
|
|
# Schema 错误
|
|
- id: MISSING_SCHEMA_TYPE
|
|
pattern: components.schemas.*.type
|
|
severity: warning
|
|
category: schema
|
|
title: Missing Schema Type
|
|
description: Schema should specify a type for better code generation.
|
|
suggestions:
|
|
- description: Add a type field to the schema
|
|
codeExample: '"type": "object"'
|
|
|
|
- id: CIRCULAR_REFERENCE
|
|
pattern: components.schemas.*
|
|
severity: warning
|
|
category: schema
|
|
title: Circular Reference Detected
|
|
description: Circular references can cause issues in code generation.
|
|
suggestions:
|
|
- description: Consider using allOf or breaking the circular dependency
|
|
codeExample: '"allOf": [{ "$ref": "#/components/schemas/BaseModel" }]'
|
|
|
|
# 安全方案错误
|
|
- id: MISSING_SECURITY_SCHEME_TYPE
|
|
pattern: components.securitySchemes.*.type
|
|
severity: error
|
|
category: security
|
|
title: Missing Security Scheme Type
|
|
description: Security scheme must specify a type.
|
|
suggestions:
|
|
- description: Add a type field (apiKey, http, oauth2, openIdConnect)
|
|
codeExample: '"type": "apiKey"'
|
|
|
|
- id: MISSING_API_KEY_NAME
|
|
pattern: components.securitySchemes.*.name
|
|
severity: error
|
|
category: security
|
|
title: Missing API Key Name
|
|
description: API Key security scheme must specify a parameter name.
|
|
suggestions:
|
|
- description: Add name field for API key parameter
|
|
codeExample: '"name": "X-API-Key"'
|
|
|
|
- id: MISSING_API_KEY_LOCATION
|
|
pattern: components.securitySchemes.*.in
|
|
severity: error
|
|
category: security
|
|
title: Missing API Key Location
|
|
description: API Key security scheme must specify where the key is located.
|
|
suggestions:
|
|
- description: Add in field (query, header, cookie)
|
|
codeExample: '"in": "header"'
|
|
|
|
# 响应错误
|
|
- id: MISSING_RESPONSE_DESCRIPTION
|
|
pattern: paths.*.*.responses.*.description
|
|
severity: warning
|
|
category: bestPractice
|
|
title: Missing Response Description
|
|
description: Response should have a description.
|
|
suggestions:
|
|
- description: Add a description for the response
|
|
codeExample: '"description": "Successful operation"'
|
|
|
|
- id: NO_SUCCESS_RESPONSE
|
|
pattern: paths.*.*.responses
|
|
severity: warning
|
|
category: bestPractice
|
|
title: No Success Response
|
|
description: Operation should define at least one success response (2xx).
|
|
suggestions:
|
|
- description: Add a success response
|
|
codeExample: '"200": { "description": "Success" }'
|
|
|
|
# 性能和最佳实践
|
|
- id: MISSING_OPERATION_ID
|
|
pattern: paths.*.*.operationId
|
|
severity: warning
|
|
category: bestPractice
|
|
title: Missing Operation ID
|
|
description: Operation should have an operationId for better code generation.
|
|
suggestions:
|
|
- description: Add a unique operationId
|
|
codeExample: '"operationId": "getUsers"'
|
|
|
|
- id: MISSING_OPERATION_SUMMARY
|
|
pattern: paths.*.*.summary
|
|
severity: info
|
|
category: bestPractice
|
|
title: Missing Operation Summary
|
|
description: Operation should have a summary for better documentation.
|
|
suggestions:
|
|
- description: Add a brief summary
|
|
codeExample: '"summary": "Get all users"'
|
|
|
|
- id: LARGE_SCHEMA_OBJECT
|
|
pattern: components.schemas.*
|
|
severity: info
|
|
category: performance
|
|
title: Large Schema Object
|
|
description: Schema has many properties, consider breaking it down.
|
|
suggestions:
|
|
- description: Consider using composition with allOf
|
|
codeExample: '"allOf": [{ "$ref": "#/components/schemas/BaseModel" }, { "type": "object", "properties": {...} }]'
|
|
|
|
# 媒体类型错误
|
|
- id: MISSING_CONTENT_TYPE
|
|
pattern: paths.*.*.requestBody.content
|
|
severity: warning
|
|
category: validation
|
|
title: Missing Content Type
|
|
description: Request body should specify at least one content type.
|
|
suggestions:
|
|
- description: Add a content type
|
|
codeExample: '"application/json": { "schema": {...} }'
|
|
|
|
- id: INCONSISTENT_CONTENT_TYPES
|
|
pattern: paths.*
|
|
severity: info
|
|
category: bestPractice
|
|
title: Inconsistent Content Types
|
|
description: API uses different content types across operations.
|
|
suggestions:
|
|
- description: Consider standardizing on common content types
|
|
codeExample: Use application/json consistently
|