Q: What is the purpose of '--validate' flag?

[SheezZarR]

Hello! I was unable to find any information in regards to --validate command option. What does it do exactly?

Initially, I thought it was meant to trigger a non-zero exit code on errors in schema generation, but it was not the case (why?). Only --fail-on-warn resulted in a erroneous code.

I want to use schema generation in my CI/CD and, after comparing warnings and errors, I have decided to only account for errors, since they have appeared to be more significant to my schema.

[tfranzel]

So --validate means that your schema is checked against the relevent JSON Schema (OpenAPI specification) for compliance. It raises an non-zero code if anything does not look right structurally.

Spectacular has two kinds of messages: warnings and errors. Warnings are minor issues found, and errors denote a bit more severe issue like a whole endpoint not being processable. Think of it as message "severity".

By default, spectacular will not raise errors (non-zero code). However, if you want your generation to fail if a warning or error is produced, you add --fail-on-warn.

Both flags are meant to be used with CI/CD, so they should return a non-zero code if their requirements are not met.

[SheezZarR]

@tfranzel thank you for the clarification!

I was wondering if it will be a good cause to put it in the docs. What do you think? I have not really found a suitable place though...

I believe the least effort would be is to update management command spectacular with extra descriptions for both options (or just --validate). Right now descriptions are blank on the 0.27.1 version:

options:
  -h, --help            show this help message and exit
  --format {openapi,openapi-json}
  --urlconf URLCONF
  --generator-class GENERATOR_CLASS
  --file FILE
  --fail-on-warn
  --validate
  --api-version API_VERSION
  --lang LANG
  --color
  --custom-settings CUSTOM_SETTINGS
  --version             Show program's version number and exit.
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions.
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.