Comments (3)
@ShahOdin, thank you for transferring the issue. The smithy
to openapi
conversion is done at built time, by code present in this repository (which fortunately we control), specifically by this class : https://github.com/disneystreaming/alloy/blob/main/modules/openapi/src/software/amazon/smithy/openapi/fromsmithy/protocols/ExampleNode.scala#L48
The bad news is that, though it may not seem like it, this issue is extremely complex. The problem is sort of tied to your end note :
Also note that in my example, I had to provide the output example as a smithy structure rather than a json. ie {message: "Hello Jeff"} rather than msg, which I'd argue, is a little counter intuitive for the reader.
It is important to remember that Smithy is a protocol agnostic IDL. Therefore, the goal of the examples trait provided
by the smithy stand library is to define examples regardless of the protocol and serialisation, which is valuable for a number of reasons (such as documentation for generated SDKs). In particular, the fact that its use expects the user to define the inputs/outputs in terms of the canonical json-like representation in smithy means that the data it holds can be validated against the protocol agnostic definition of the data (which disregards protocol-specific traits).
It was not designed to be used in openapi, and it's us (the maintainers of smithy4s and alloy) who were overzealous in trying to make use of it in the context of openapi. I think we were wrong, because taking the protocol-agnostic representation and turning it into a protocol-specific representation (like simpleRestJson
) that abides by all the traits relevant to that protocol (like jsonName
) is a really really hard problem to solve generically at build time, because protocols can have differences in semantics based on what traits they support. For instance, our simpleRestJson
protocol allows for several encodings for unions, which is not something that is supported by the AWS-issued tooling. These custom encodings are also disregarded in openapi examples.
It would be possible for us to solve it at run-time (with the smithy4s constructs), and although this may be desirable in some aspects, it'd take us a fair amount of work to transition from a build-time solution to a run-time solution, and we don't currently have the bandwidth to do so.
Where does that leave us ?
I think the best course of action would be for us to :
- stop using the official
smithy.api#example
trait in openapi conversions. It's just unsound, as you've discovered it. - define a
alloy#httpPayloadExamples
trait that would take the examples not in the form of a smithy node, but rather in the form of a string.
The trade-off being that :
- The examples would no longer be validated against their models, and could come out of date
- Quotes would have to be escaped in the payloads
Regarding your question :
I understand this is perhaps one for smithy but do we know if it Would be possible to specify examples in json rather than smithy structures?
Well my reply hint at it, but considering smithy is a protocol-agnostic IDL, it is extremely unlikely that AWS will change the examples trait.
from alloy.
Thank you so much for the in depth response!
Where does that leave us ?
define a alloy#httpPayloadExamples trait that would take the examples not in the form of a smithy node, but rather in the form of a string.
The trade-off being that
purely from a user's point of view, I'd prefer a structure/Json format as input. I understand that internally you'd probably not want to parse it as a structure.
fwiw, I have decided to drop the discrepency between message
and msg
for now.
What I would suggest is making this issue more explicit in the guides etc. perhaps here? https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/overview
from alloy.
purely from a user's point of view, I'd prefer a structure/Json format as input
Well the thing is that if we put something in place, we'd likely want to re-use it for other serialisations than json, so even if the smithy json-looking "node" (that's what they're called btw) seems like a good idea, I don't think it actually is ...
Anyway, we'll give it a think when we find the time (it may not be for a while though, we're pretty swamped with more urgent stuff at work). If you want to take a go at it, I'm happy to give some guidance.
What I would suggest is making this issue more explicit in the guides etc. perhaps here?
Good point, I'll give it a think. Thanks for the suggestion.
from alloy.
Related Issues (8)
- Alloy OpenApi module import issue HOT 9
- Link to constraints and behavioural traits in Readme is broken HOT 1
- Add protocol compliance tests for union encodings
- Add protocol compliance tests for nullable
- Support @nullable in simpleRestJson smithy to openapi conversion HOT 1
- allow specifying open api servers when constructing swagger docs
- Fields annotated with uuidFormat should result in uuid formatted string in the generated swagger docs
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from alloy.