Fix final layer of error handling in command plugin #795

simonjbeaumont · 2025-07-16T06:30:45Z

Motivation

When the generator is run as a command plugin on a correctly configured target but there are problems generating, there's a layer of error handling which is incorrect resulting in a poor user experience. For example, if the OpenAPI document contains a bad type like this...

components:
  schemas:
    BadIntHolder:
      type: object
      description: A value that has a bad typed int.
      properties:
        int:
          type: int
          description: A bad type

...then the command plugin shows the following output:

Considering target 'HelloWorldURLSessionClient':
- Trying OpenAPI code generation.
/Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml: error: Found neither a JSONType nor a Arr
ay<JSONType> in Document.components.schemas.Greeting.properties.i.type.

JSONType could not be decoded because:
Inconsistency encountered when parsing `[unknown object]`: Cannot initialize JSONType from invalid String value int.

Array<JSONType> could not be decoded because:
Expected value to be parsable as Sequence but it was not..
Error: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml: error: Found neither a JSONType no
r a Array<JSONType> in Document.components.schemas.Greeting.properties.i.type.

JSONType could not be decoded because:
Inconsistency encountered when parsing `[unknown object]`: Cannot initialize JSONType from invalid String value int.

Array<JSONType> could not be decoded because:
Expected value to be parsable as Sequence but it was not..
Swift OpenAPI Generator is running with the following configuration:
- OpenAPI document path: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml
- Configuration path: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi-generator-config.yaml
- Generator modes: types, client
- Access modifier: internal
- Naming strategy: idiomatic
- Name overrides: <none>
- Type overrides: <none>
- Feature flags: <none>
- Output file names: Types.swift, Client.swift
- Output directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/GeneratedSources
- Diagnostics output path: <none - logs to stderr>
- Current directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example
- Plugin source: command
- Is dry run: false
- Additional imports: <none>
- Additional file comments: <none>
- Stopping because target isn't configured for OpenAPI code generation.
error: Targets with names HelloWorldURLSessionClient don't contain any config or OpenAPI document files with expected names. See documentation for details.

There are two issues with this:

The final error is just plain wrong.
Because the diagnostics are printed to stderr and the big info message to stdout they are ordered wrongly—you get the diagnostics before the message saying how the generator will run.

Modifications

Fix the categorisation of errors in the command plugin.
Print the big info message to stderr.

Result

Command plugin now correctly categorises misconfiguration errors vs other errors and provides more appropriate output on failure.

The above example now results in:

Considering target 'HelloWorldURLSessionClient':
- Trying OpenAPI code generation.
Swift OpenAPI Generator is running with the following configuration:
- OpenAPI document path: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml
- Configuration path: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi-generator-config.yaml
- Generator modes: types, client
- Access modifier: internal
- Naming strategy: idiomatic
- Name overrides: <none>
- Type overrides: <none>
- Feature flags: <none>
- Output file names: Types.swift, Client.swift
- Output directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/GeneratedSources
- Diagnostics output path: <none - logs to stderr>
- Current directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example
- Plugin source: command
- Is dry run: false
- Additional imports: <none>
- Additional file comments: <none>/Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml: error: Found neither a JSONType nor a Array<JSONType> in Document.components.schemas.Greeting.properties.int.type.

JSONType could not be decoded because:
Inconsistency encountered when parsing `[unknown object]`: Cannot initialize JSONType from invalid String value int.

Array<JSONType> could not be decoded because:
Expected value to be parsable as Sequence but it was not..
Error: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example/Sources/HelloWorldURLSessionClient/openapi.yaml: error: Found neither a JSONType nor a Array<JSONType> in Document.components.schemas.Greeting.properties.int.type.

JSONType could not be decoded because:
Inconsistency encountered when parsing `[unknown object]`: Cannot initialize JSONType from invalid String value int.

Array<JSONType> could not be decoded because:
Expected value to be parsable as Sequence but it was not..
- OpenAPI code generation failed with error.
error: The generator failed to generate OpenAPI files for target 'HelloWorldURLSessionClient'.

Related issues

Fixes Invalid openapi.yaml produces unexpected diagnostic message #794

simonjbeaumont · 2025-07-16T06:32:35Z

//cc @MaxDesiatov

czechboy0

Thanks!

MaxDesiatov

Does this actually output the validation error? I don't see that changed in the diff, but I'm not familiar with the code to say for sure

simonjbeaumont · 2025-07-16T08:11:39Z

@MaxDesiatov the validation output was always printed (it should have been in your output already, just way up because of the stderr/stdout flushing differences). You can see in the examples in the PR description that they were printed in both cases too. Now they'll be printed in the correct order and you'll see them right before the final error.

Would you mind running your repro against this branch to confirm?

MaxDesiatov · 2025-07-16T09:11:24Z

I see, yes it's at the top, which I personally find unobvious. May I suggest that separating the error messages to be placed on adjacent lines? - OpenAPI code generation failed with error with actual error context dozens of lines above feels disconnected. If placing them on adjacent lines requires significant changes, maybe it could say "see the detailed error message above" or smth like that?

simonjbeaumont · 2025-07-16T13:40:48Z

@MaxDesiatov I'm just wanting to confirm things here... your comment on this PR says:

I see, yes it's at the top, which I personally find unobvious. May I suggest that separating the error messages to be placed on adjacent lines? - OpenAPI code generation failed with error with actual error context dozens of lines above feels disconnected.

To be clear, we have solved exactly that in this PR. The weird ordering was the use of both stdout and stderr. It should now be the case that the final output of the tool in this failure mode is an error that it couldn't generate and, right above that, will be the errors.

But... in your comment on the issue you say

No I never saw this in the output. That was the most misleading thing in the current diagnostic behavior. For some time I thought the generator couldn't discover the OpenAPI document at all.

I'm pretty sure that this PR addresses your issue but I'd like to make sure I haven't missed something before we cut a release 🙏

MaxDesiatov · 2025-07-16T13:44:52Z

Sorry, the error message was there, but it was cut off because my terminal height was set to just a few lines. I didn't notice it because of the ordering. If changing from stdout to stderr fixes the ordering issue, that's much appreciated, thanks!

MahdiBM · 2025-07-16T15:23:44Z

Plugins/OpenAPIGeneratorCommand/plugin.swift

                if error.isMisconfigurationError {
-                    print("- OpenAPI code generation failed with error.")
+                    print("- Stopping because target isn't configured for OpenAPI code generation.")


This is not quite right though.

When isMisconfigurationError is true, It's pretty much certain that the user configured their target for openapi, but did it wrong.

When isMisconfigurationError is false, it can be either a misconfiguration or no-configuration.

Or at least that's what I intended with this code, IIRC.

Not defending the existing message and handling. Just saying the new message/handling can also be improved.

That's fair, how about we just tweak this one?

Suggested change

if error.isMisconfigurationError {

print("- OpenAPI code generation failed with error.")

print("- Stopping because target isn't configured for OpenAPI code generation.")

if error.isMisconfigurationError {

print("- Stopping because target is misconfigured for OpenAPI code generation.")

//cc @MahdiBM @czechboy0

…et argument (#798) ### Motivation In #795 we adjusted the logic of the command plugin because errors were not propagating properly. As a result, we regressed behaviour when the command plugin was run without any `--target` argument. In this mode, the plugin runs on all targets. When it detects a misconfigured target it errors, as it should. However, the classification of misconfigured target included targets that were not intended for code generation at all, resulting in errors running the command plugin on packages with others targets. ### Modifications - Add command plugin generation step to integration test - If the command plugin is running without a `--target` argument and cannot find _any_ of the required files, skip that target. ### Result - Manual code generation with the command plugin fixed for packages with other targets. - Fixes #797. ### Test Plan This PR includes two commits. The first adds a step to the integration test, which runs the command plugin on the integration test package. This will fail in CI. Then the second commit will provide the fix, which should pass in CI. The commits will then be squash merged.

simonjbeaumont added 2 commits July 16, 2025 07:19

Fix final layer of error handling in command plugin

eaf436f

Print notice of generator run to stderr

33886c8

simonjbeaumont requested a review from czechboy0 July 16, 2025 06:31

simonjbeaumont added the 🔨 semver/patch No public API change. label Jul 16, 2025

czechboy0 approved these changes Jul 16, 2025

View reviewed changes

MaxDesiatov reviewed Jul 16, 2025

View reviewed changes

MahdiBM reviewed Jul 16, 2025

View reviewed changes

Merge branch 'main' into sb/command-plugin-errors

a5b64af

czechboy0 approved these changes Jul 17, 2025

View reviewed changes

simonjbeaumont merged commit f876c5a into apple:main Jul 17, 2025
35 checks passed

This was referenced Jul 23, 2025

Manually generating code fails if package includes additional targets #797

Closed

Command plugin should skip irrelevant targets when run without --target argument #798

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix final layer of error handling in command plugin #795

Fix final layer of error handling in command plugin #795

Uh oh!

simonjbeaumont commented Jul 16, 2025 •

edited

Loading

Uh oh!

simonjbeaumont commented Jul 16, 2025

Uh oh!

czechboy0 left a comment

Uh oh!

MaxDesiatov left a comment

Uh oh!

simonjbeaumont commented Jul 16, 2025 •

edited

Loading

Uh oh!

MaxDesiatov commented Jul 16, 2025

Uh oh!

simonjbeaumont commented Jul 16, 2025

Uh oh!

MaxDesiatov commented Jul 16, 2025 •

edited

Loading

Uh oh!

MahdiBM Jul 16, 2025 •

edited

Loading

Uh oh!

MahdiBM Jul 16, 2025

Uh oh!

simonjbeaumont Jul 16, 2025

Uh oh!

Uh oh!

Uh oh!

Fix final layer of error handling in command plugin #795

Fix final layer of error handling in command plugin #795

Uh oh!

Conversation

simonjbeaumont commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Modifications

Result

Related issues

Uh oh!

simonjbeaumont commented Jul 16, 2025

Uh oh!

czechboy0 left a comment

Choose a reason for hiding this comment

Uh oh!

MaxDesiatov left a comment

Choose a reason for hiding this comment

Uh oh!

simonjbeaumont commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MaxDesiatov commented Jul 16, 2025

Uh oh!

simonjbeaumont commented Jul 16, 2025

Uh oh!

MaxDesiatov commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MahdiBM Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MahdiBM Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

simonjbeaumont Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

simonjbeaumont commented Jul 16, 2025 •

edited

Loading

simonjbeaumont commented Jul 16, 2025 •

edited

Loading

MaxDesiatov commented Jul 16, 2025 •

edited

Loading

MahdiBM Jul 16, 2025 •

edited

Loading