Validating API specifications in API Insights

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 9분

    • You can access API specification validation rules to verify that your API specifications are complete, consistent, and adhere to best practices.

    Validation rules identify structural issues early during import or analysis, improving overall API quality. You can manage these rules to enforce standardization across API specifications and reduce errors by checking for missing or incorrect fields before APIs are published or used in production.

    Storing API specifications

    The API Specification [sn_api_insights_ws_api_specification] table stores the specification documents that describe individual APIs. Each record includes the following details to identify the API to which the specification belongs and to manage multiple versions.
    표 1. API specification details
    Field Description
    Name Name of the API.
    Version Version of the API.
    Type Format and version of the API specification standard being used. For example, openapi3.0.0 for an OpenAPI specification.
    State Current status indicating whether the API specification has been validated against the applicable rules and the validation outcome. Valid values are:
    • Unprocessed: Indicates that the API specification hasn’t been validated.
    • Valid: Indicates that the API specification was validated and processed successfully or with warnings. If warnings are present, details are displayed in the Message field.
    • Invalid: Indicates that the API specification was validated but contains errors. Error details are displayed in the Message field.
    Specification Full content of the API specification file.
    주:
    For OpenAPI, includes the complete OpenAPI document describing endpoints, methods, and schema.
    Message Messages are generated after processing all validation rules for the specification type. They include errors or warnings with explanations.

    Validation rule structure

    The Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table stores validation rules for the API specifications defined in the API Specification [sn_api_insights_ws_api_specification] table.
    주:
    The sn_cmdb_editor role is required to edit or delete validation rules, and the cmdb_read role to view them.

    Each validation rule contains the following key components:

    표 2. Validation rule components
    Component Description
    Specification API specification for which the rule is designed.
    Version Version of the API specification the rule validates. If specified, the rule applies only to those versions. To restrict validation to specific versions, specify them in the Version field. Separate multiple values with commas. For example, 1.0,1.1,2.0.
    주:
    If the Version field is left empty, the rule runs for all installed versions of the specified API specification type.
    Type Type of validation to perform. The valid values are:
    • Path: Verifies that the specific keys are present within arrays of objects, individual objects, or both, in the designated sections of the API specification document.
    • Expected value: Validates whether the specified key matches the expected values specified in the Value field. This validation applies only to a single key specified in the Key field.
    Key Part of the specification to verify. If no expected value is provided, you can enter multiple keys in the Key field, separated by commas.
    Value Expected values for the key specified in the Key field. Separate multiple values with commas.
    Severity Severity level of the validation rule outcome, either a warning or an error.
    주:
    When set to warning, the API specification remains valid if the rule isn’t met, indicating it is not a failure, and only a message is displayed.
    Message Explanation of the issue when the rule is triggered.
    Active Option to activate the rule. Only active rules are triggered by the API Specification Validation scheduled job.

    API specification validation process

    The API Specification Validation scheduled job automatically validates unprocessed API specifications against active rules based on their specification type to ensure compliance with required standards.

    The validation process includes:
    1. Retrieving all active validation rules from the Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table.
    2. Selecting APIs marked as unprocessed in the API Specification [sn_api_insights_ws_api_specification] table.
    3. Applying relevant validation rules to each selected API based on its specification type, such as OpenAPI.
    4. Verifying the presence or correctness of specific fields or their values within the API specification.
    5. Updating the processing status and capturing any errors or warnings.

    Predefined rules for OpenAPI specifications

    By default, the application includes the following validation rules for OpenAPI specifications:
    Validate tags
    Verifies that each tag in the API specification includes a name field. If the name field is missing, the system returns a warning message but marks the specification as valid.
    Validate required sections
    Verifies that the API specification includes the required top-level sections: info, paths, and components. If any of these sections are missing, the system returns an error message and marks the specification as invalid.
    Validate servers section
    Verifies whether the API specification includes a servers section that defines the server endpoints. If the servers section is missing, the system returns an error message and marks the specification as invalid.

    These predefined rules verify critical sections such as tagging, metadata, and server definitions in OpenAPI specifications.