swagger-api / swagger-api/swagger-parser

Permit accessing "extra" structures and fields left over after OpenAPIDeserializer parses everything

Open
#1,363 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

So, as always, thank you for your work maintaining swagger-parser, it has made my task writing and maintaining guardrail orders of magnitude easier.

One challenge I've experienced recently is how to effectively communicate to the user when they've used an OpenAPI 2.x structure in a 3.x document.

To this end, I'd like to modify OpenAPIDeserializer to copy() the JsonNode rootNode at the beginning of deserialize, and as it successfully consumes fields (via the get* functions), it removes them from the tree, maintaining a reference, and if the structure (in my case, primarily thinking about ObjectNode) is not empty, attaching that as a new field on each of the associated swagger-models.

This represents a fairly significant deviation from how the current parser works, but I think it would permit all consumers of swagger-parser to produce much more helpful error messages, guiding users to why their specification is not working as they intend.

I'd appreciate some feedback on this idea (has it been tried before? Does it already exist in the repo, possibly a strict validation extension to the underlying parser, and I've just missed it somehow?)

Thank you for the consideration, I'd be more than happy to attempt to implement it if this seems reasonable.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading OpenAPIDeserializer.deserialize, including the JsonNode rootNode handling and the get* functions that consume fields. Then inspect how the swagger-models are structured. The issue needs an agreed design for retaining unconsumed structures and attaching them to models; done would include that implementation and validation of the resulting user-facing errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.