NAME

OpenAPI::Linter - Validate and lint OpenAPI specifications

VERSION

Version 0.05

SYNOPSIS

use OpenAPI::Linter;

# Create a linter from a file
my $linter = OpenAPI::Linter->new(spec => 'openapi.yaml');

# Or from a hashref
my $linter = OpenAPI::Linter->new(spec => $openapi_hash);

# Find issues in the specification
my @issues = $linter->find_issues;

# Filter issues by level or pattern
my @warnings = $linter->find_issues(level => 'WARN');
my @path_issues = $linter->find_issues(pattern => qr/paths?/i);

# Validate against JSON Schema
my @schema_errors = $linter->validate_schema;

DESCRIPTION

OpenAPI::Linter provides comprehensive validation and linting for OpenAPI specifications. It checks both structural correctness against the official JSON Schema and performs additional linting for best practices and common issues.

The module supports OpenAPI versions 3.0.x and 3.1.x, automatically detecting the specification version from the provided document.

METHODS

new

my $linter = OpenAPI::Linter->new(spec => $file_path_or_hashref);
my $linter = OpenAPI::Linter->new(spec => $hashref, version => '3.0.3');

Creates a new OpenAPI::Linter instance. The constructor accepts:

spec

Required. Either a file path to an OpenAPI specification (YAML or JSON) or a hash reference containing the parsed OpenAPI specification.
version

Optional. Explicitly set the OpenAPI version. If not provided, the version will be auto-detected from the specification.

find_issues

Finds and returns linting issues in the OpenAPI specification. Returns a list of issue hashes in list context, or an array reference in scalar context.

Each issue hash contains:

{
    level   => 'ERROR' | 'WARN',  # Issue severity level
    message => 'Human readable description of the issue'
}

Parameters:

level

Filter issues by severity level. Either ERROR or WARN.
pattern

Filter issues by message pattern (regular expression).

my @all_issues = $linter->find_issues;
my @issues = $linter->find_issues(level => 'ERROR');
my @issues = $linter->find_issues(pattern => qr/missing/i);
my @issues = $linter->find_issues(level => 'WARN', pattern => qr/description/);

validate_schema()

my @schema_errors = $linter->validate_schema;
my $schema_errors = $linter->validate_schema;

Validates the OpenAPI specification against the official JSON Schema for the detected OpenAPI version. Returns a list of validation errors in list context or an array reference in scalar context.

This method uses JSON::Validator to perform schema validation and returns errors in the format provided by that module.

APPLICATION

openapi-lint is a command-line tool that validates OpenAPI specifications for both structural correctness and best practices. It uses the OpenAPI::Linter module to perform comprehensive checks on OpenAPI documents.

The tool can operate in two modes:

1. Linting mode (default): Checks for best practices, missing required fields and common issues in OpenAPI specifications.
2. Schema validation mode: Validates the specification against the official OpenAPI JSON Schema for the detected version.

OPTIONS

--spec specfile: Required. Path to the OpenAPI specification file. The file can be in either YAML (.yaml, .yml) or JSON (.json) format.
--version version: Specify the OpenAPI version explicitly (e.g., 3.0.3, 3.1.0). If not provided, the version will be auto-detected from the openapi field in the specification.
--json: Output results in JSON format instead of human-readable text. This is useful for programmatic consumption of the results.
--validate: Run schema validation instead of lint checks. This mode validates the specification against the official OpenAPI JSON Schema rather than performing custom linting rules.
--help: Display this help message and exit.

EXAMPLES

Basic Usage

openapi-lint --spec api.yaml

Run linting checks on api.yaml and display results in human-readable format.

Schema Validation

openapi-lint --spec api.json --validate

Validate api.json against the official OpenAPI JSON Schema.

JSON Output

openapi-lint --spec api.yaml --json

Run linting checks and output results in JSON format for programmatic processing.

Specific Version

openapi-lint --spec api.yaml --version 3.1.0

Run linting checks assuming OpenAPI version 3.1.0, overriding auto-detection.

OUTPUT FORMATS

Human Readable Output (Default)

The default output format displays issues in a readable format:

[ERROR] Missing info.title
[WARN] Missing info.description
[ERROR] Missing info.version

Summary: 2 ERRORs, 1 WARN

Exit Codes

0: No issues found
1: Issues found (errors and/or warnings)
2: Usage error

JSON Output

When using --json, the output is structured JSON:

{
    "summary": {
        "errors": 2,
        "warnings": 1
    },
    "issues": [
        {
            "level": "ERROR",
            "message": "Missing info.title"
        },
        {
            "level": "WARN",
            "message": "Missing info.description"
        },
        {
            "level": "ERROR",
            "message": "Missing info.version"
        }
    ]
}

LINTING CHECKS

When running in linting mode (default), the tool checks for:

Required root elements (openapi, info, paths)
Required info object fields (title, version)
Recommended info object fields (description, license)
Operation descriptions for all paths and methods
Schema type definitions and property descriptions

SCHEMA VALIDATION

When using --validate, the tool validates the specification against the official OpenAPI JSON Schema for the detected version. This checks:

Structural correctness of the specification
Data types and format compliance
Required fields according to the OpenAPI specification
Valid references and schema composition

SUPPORTED OPENAPI VERSIONS

OpenAPI 3.0.0, 3.0.1, 3.0.2, 3.0.3
OpenAPI 3.1.0, 3.1.1

DIAGNOSTICS

"spec = HASHREF required if no file provided">: The spec parameter to new must be either a file path or a hash reference containing the OpenAPI specification.
"Unsupported OpenAPI version: %s": The OpenAPI version specified in the document or provided to the constructor is not supported.

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/OpenAPI-Linter

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/OpenAPI-Linter/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc OpenAPI::Linter

You can also look for information at:

BUG Report

https://github.com/manwar/OpenAPI-Linter/issues
CPAN Ratings

http://cpanratings.perl.org/d/OpenAPI-Linter
Search MetaCPAN

https://metacpan.org/dist/OpenAPI-Linter/

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To install OpenAPI::Linter, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenAPI::Linter

CPAN shell

perl -MCPAN -e shell
install OpenAPI::Linter

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new

find_issues

validate_schema()

APPLICATION

OPTIONS

EXAMPLES

Basic Usage

Schema Validation

JSON Output

Specific Version

OUTPUT FORMATS

Human Readable Output (Default)

Exit Codes

JSON Output

LINTING CHECKS

SCHEMA VALIDATION

SUPPORTED OPENAPI VERSIONS

DIAGNOSTICS

SEE ALSO

AUTHOR

REPOSITORY

BUGS

SUPPORT

LICENSE AND COPYRIGHT

Module Install Instructions