Invalid `openapi.yaml` produces unexpected diagnostic message

[MaxDesiatov]

Description

When a typo is made or a wrong property name is used in openapi.yaml schema declaration, no relevant diagnostic message is provided when running swift package generate-code-from-openapi. The only error message seen is this one:

Targets with names FooTarget don't contain any config or OpenAPI document files with expected names.

This message is incorrect, since both config and OpenAPI document are provided in the expected location. The actual underlying reason is that the OpenAPI document didn't pass validation, but validation diagnostic is not produced, which is very confusing.

Reproduction

Create an OpenAPI document that uses int and double types in the schema instead of integer and number:

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /summary:
    get:
      operationId: getSummary
      parameters:
        - name: name
          required: false
          in: query
          description: The name used in the returned greeting.
          schema:
            type: string
      responses:
        '200':
          description: A success response with a greeting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Greeting'
components:
  schemas:
    Greeting:
      type: object
      properties:
        message:
          type: string
        floatingPoint:
          type: double
        integerValue:
          type: int

Package version(s)

      "location" : "https://github.com/apple/swift-openapi-generator.git",
      "state" : {
        "revision" : "ea291f05436363665ee67c453f4a72a895f18e75",
        "version" : "1.9.0"
      }

Expected behavior

If openapi.yaml doesn't pass validation, a validation error should be produced, ideally with line/column information and an actionable suggestion for how the error can be fixed.

Environment

> swift --version
swift-driver version: 1.120.5 Apple Swift version 6.1.2 (swiftlang-6.1.2.1.2 clang-1700.0.13.5)
Target: arm64-apple-macosx15.0

Additional information

No response

[simonjbeaumont]

That’s surprising since we have validation logic that should emit warnings or errors and even with source location so that editors can show them. Sounds like we have an edge case we’re missing here.

[simonjbeaumont]

Appears to produce the expected diagnostics, but the final error is misleading:

Build of product 'swift-openapi-generator' complete! (3.58s)
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 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..
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.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>
- 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>
- 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.

@MaxDesiatov can you confirm you also see something similar to this in your output?

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

[simonjbeaumont]

Running the tool directly results in this more helpful output, exiting non-zero:

❯ .build/plugins/tools/debug/swift-openapi-generator-tool generate --mode types --config Sources/HelloWorldURLSessionClient/openapi-generator-config.yaml Sources/HelloWorldURLSessionClient/openapi.yaml
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
- Access modifier: internal
- Naming strategy: idiomatic
- Name overrides: <none>
- Feature flags: <none>
- Output file names: Types.swift
- Output directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/Examples/hello-world-urlsession-client-example
- 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: <none>
- Is dry run: false
- Additional imports: <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.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 nor 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..

I think this must be how it composes with being run as a command plugin.

[simonjbeaumont]

Yep, this'll be it, in the command plugin code:

            do {
                print("- Trying OpenAPI code generation.")
                try runCommand(
                    targetWorkingDirectory: target.directory,
                    tool: context.tool,
                    sourceFiles: swiftTarget.sourceFiles,
                    targetName: target.name
                )
                print("- ✅ OpenAPI code generation for target '\(target.name)' successfully completed.")
                hadASuccessfulRun = true
            } catch let error as PluginError {
                if error.isMisconfigurationError {
                    print("- OpenAPI code generation failed with error.")
                    throw error
                } else {
                    print("- Stopping because target isn't configured for OpenAPI code generation.")
                }
            }

For some reason, this error is being mis-categorised.

[MaxDesiatov]

@MaxDesiatov can you confirm you also see something similar to this in your output?

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

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.