Openapi-generator: CLI: add info about unused schemas in the validate command

[jmini]

With #74, the method ModelUtils.getUnusedSchemas(OpenAPI) was updated. It computes the list of unused schema.
We could append this information to the output of the validate task. It is a kind of information that something is not right in the schema.

What do you think?

cc: @ackintosh (you seems to use this feature, are you interested?)

[jimschubert]

I would expect validate to only say whether or not a spec is valid. Unused models isn't invalid.

Maybe a switch like --recommend to output this additional information?

We could add nested commands as well. For example:

cli check valid
cli check unused
cli check security
etc

This way there wouldn't be confusion about the use cases.

[ackintosh]

I like the switch --recommend.

• Unused schema is not invalid as a specification
• I want to notice if there's an unused schema (or something wrong matters)
• As one of validate users, I hope the above features will be realized with single command
  
  
  
  • Since I'm using it in CI, I think it is helpful to check various points of view (recommended by the generator) with a single command
  
  

the switch is suitable for satisfying the above. 💡

[jimschubert]

@ackintosh In #251, I have added warnings to the errors you'd normally receive with validation. With that PR, we'd begin validating on every generation by default. Rather than having multiple switches to enable/disable validation and enable/disable recommendations, I've rolled them into errors and warnings.

On generation, you'll only see these warnings _if_ errors are present. The message would look like this from the gradle plugin:

$ gradle generateGoWithInvalidSpec
> Task :generateGoWithInvalidSpec FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':generateGoWithInvalidSpec'.
> Specification has failed validation. | Error count: 1, Warning count: 1
  Errors:
        -attribute info is missing
  Warnings:
        -Unused model: Pet


* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 1s
1 actionable task: 1 executed

So for the CLI validate command, I was wondering if we should perform error+warning by default or, if you pass --recommend it would show recommendations even if you don't have errors. Which sounds best for openapi-generator-cli validate --recommend?

[matteomazza91]

I think that we can consider different behaviors (exit code) useful for CI as well as pretty output-format capability. Something like:

openapi-generator-cli validate should

• print errors and warnings
• result in a failure if at least one error is found

openapi-generator-cli validate --recommend should

• print errors and warnings
• result in a failure if at least one error or warning is found

openapi-generator-cli validate --ignore-recommend should

• print errors only
• result in a failure if at least one error is found

[ackintosh]

My idea is based on making it as simple as possible. From that point of view, here is my suggestion:

1. openapi-generator-cli validate

Users who run this command want to know if their spec is valid.

So the CLI should behave:

• print errors
• result in a failure if errors are present

2. openapi-generator-cli validate --recommend

Users who run this command want to know wherther there are any matters as well as whether their spec is valid.

So the CLI should behave:

• print errors + warnings
  
  
  
  • print warnings even if there are not errors.
  
  
• result in a failure if errors or warnings are present

[jimschubert]

@ackintosh I like that suggestion best. However, for the second case I think it would make more sense to return an error code only if there are errors. If you validate and say "by the way, let me know of suggestions" I don't think that is technically a reason to exit with a status 1. Or is your thought that someone would be piping stderr somewhere and they'd want all errors and warnings as well as a failure if any exist? If it's the latter, I think we'd need to document that in the comment on --recommend because I would personally be surprised by that behavior.

[ackintosh]

@jimschubert I agree with you. There is no technically reason to exit with status 1 if errors are not present ( = if input spec is valid). 💡

[jimschubert]

I'll work on updating to include this --recommend option tonight.

[jimschubert]

I opened #292 to implement --recommend please check it out ;D

[jimschubert]

The implementation of #292 has been merged and exists in recent releases. Closing this. If issues arise, please reopen.