-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Message body serialization adapters #372
Comments
This was referenced Apr 20, 2020
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
In order to serialize message bodies when generating examples for request/response body from a data structure, we can provide numerous adapters for serializing content. For example serializing a data structure element into JSON, multipart form, JSON Schema or MSON etc.
Components:
Serialize should return a parse result. They should be able to emit warnings and errors. This is a problem in the current design, for example serialising API Blueprint or OpenAPI can result in loss of information which isn't clear to the end user during conversion. Loss of information should create warnings, and we should have source map information where possible.
"This line from my OAS 2 document cannot be serialized into API Blueprint because X".
Other parsers such as OAS 2 and OAS 3 should make use of the registered serializers when generating message bodies (where generateMessageBody option is enabled). The parser consumer may load JSON if they want to generate JSON bodies, or custom adapters such as yaml, messagepack, protobuf etc.
Extra note: "Console" functionality in documentation can provide a UI for entering the data structures, headers, parameters which can update value in a copy of the data structure elements. It can use these adapters to generate the message body so it does not have to duplicate the efforts for each content-type.
Here's a rough idea of how this might look and how you can use these
adapters:
The above interface expects that the input element is frozen so it can traverse up to the parents to resolve any references. We likely want to be able to provide a cache so that there is no duplicate efforts when resolving numerous
structures which contain shared references in the same document. Possible you can register a cache with the namespace, perhaps something like:
Adapters will be able to detect cache and utilise them to prevent redundant expensive work during serializing recursive structures:
The text was updated successfully, but these errors were encountered: