Validation errors and warnings are not handled in OAS resolver

[ubiuser]

An important use case for having fully resolved OpenAPI specifications is to generate code from them. When the document has validation errors and unresolved references then it is useless for this purpose.

Unfortunately, OpenAPI specs are incomplete for most APIs: hmrc/income-tax-mtd-changelog#318
Even though these public API specs should be fixed in their respective repositories, this service should probably either warn the user about validation errors or not to return incomplete specifications at all.

Parsing and bundling is handled in the fetchOasResolved function, where the construct that holds validation errors and warnings seems to be only logged at info level (see parserResult.getMessages()).

Should handleFailure be called instead of handleSuccess when parserResult.getMessages() != null ?

[DavidRobb]

Is this the reason why the self-employment-business-api yaml file at https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/self-employment-business-api/5.0/oas/resolved does not contain any details about an Annual submission payload?

As a developer, how are we supposed to code a suitable message without resorting to manually glueing all the fields together. Then trying to maintain this when HMRC decide to change the content at a later date? Shocking!!!

[ubiuser]

I spent some more time on this, but I'm not sure exactly why the APIs are incomplete. A possibility that came to mind, based on seeing all kinds of redocly linter warnings, is that the API specification sources might not follow the standards. It would be useful to know if the docs are validated at all in any pipelines, and if so then by what tool.

I'm testing a workaround, where the idea is to use local versions of the API services to generate bundles. The reason for this is that running the services will resolve the feature switch handlebars that are used in several places. Then I use the service URL as input for the bundle generation in a tool of my choice.

My workflow is the following:

• Install prerequisites: Java, Scala and sbt
• Clone an API repo and replace the LICENCE file with this one. Find more on why I do this here.
• Run sbt run.
• Use the API service's URL for the application.yaml in redocly. This will resolve all $ref (except the ones in examples, but that is the expected behaviour) and create a bundle. Examples:
  • self-employment-business-api:

    redocly bundle -d --output self-employment-business-api.yaml http://localhost:7801/api/conf/5.0/application.yaml
    

  • individual-calculations-api:

    redocly bundle -d --output individual-calculations-api.yaml http://localhost:9767/api/conf/8.0/application.yaml
    

I noticed that the redocly linter still flags a ton of issues (with the recommended settings), so my level of trust in the generated bundle is a bit low, but the result is still better than what we can download.

Please also note that there are clear differences between tools. For example, redocly is able to resolve entries in the Self Employment Business API that swagger-parser can't. Compare the results of

redocly bundle -d --output self-employment-business-api-redocly.yaml http://localhost:7801/api/conf/5.0/application.yaml

and

java -jar swagger-parser-cli-2.1.36.jar -resolve -resolveFully -yaml -o self-employment-business-api-swagger.yaml -i http://localhost:7801/api/conf/5.0/application.yaml