swagger.py

import subprocess
import sys

# pip install PyYAML
import yaml


def lint_keys(data, keys):
    """Recursively lint the given data.
    """
    for k, v in data.items():
        if isinstance(v, dict):
            lint_keys(v, keys)
        elif k in keys:
            # NOTE: We use `--ext=.md` since the Petstore example
            # uses Markdown formatting in its descriptions.
            print(subprocess.check_output(["vale", "--ext=.md", "--no-exit", v]))


def lint(spec, sections, keys):
    """A lint a given OpenAPI specification file.
    """
    with open(spec, "r") as s:
        doc = yaml.load(s)
        for section in [s for s in doc if s in sections]:
            lint_keys(doc[section], keys)


if __name__ == "__main__":
    lint(
        sys.argv[1],
        # A list of spec sections to lint:
        sections=["info", "paths"],
        # A list of the keys we want to lint:
        keys=["description", "summary"],
    )