Skip to content
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

Issue 721 - Content objects for describing request/response payloads #761

Merged
merged 10 commits into from
Sep 29, 2016

Conversation

darrelmiller
Copy link
Member

No description provided.

@zeeshanejaz
Copy link

@darrelmiller is this solely for the purpose of enabling profiles? Sorry I have been late to the party. Can you reference issues that are solved by this. Thanks.

@ePaul
Copy link
Contributor

ePaul commented Aug 19, 2016

I guess this could also solve at least parts of #146, beside #721?

@ePaul
Copy link
Contributor

ePaul commented Aug 19, 2016

As already mentioned in a comment by @fehguy in #721, there is still missing some explanation on how the schema of an application/x-www-form-urlencoded (or multipart/form-data) representation is mapped to the actual value (or the other way around), i.e. a serialization format.

As this is also missing for other kinds of parameters, I'm okay with addressing it in a separate PR, I just wanted to mention it here again. I guess #665 will have to address that too.

@darrelmiller
Copy link
Member Author

@zeeshanejaz The issues addressed by the PR mentioned in the original issue #721. Profiles are simply a way I have found to address the request that some people want to have multiple schemas for the same status code and media type.

@darrelmiller
Copy link
Member Author

@ePaul Being able to specify multiple response representations opens the door to supporting #146 but I think it is outside of the spec to try and tie a particular input parameter to the selection of the output representation. There is still a server implementation behind the API and it is up to the server to decide which representation will be returned. If the server wants to expose a parameter that directly selects the representation, then it is free to do so. I don't think the OpenAPI spec needs to get involved at this level.
As far as generating client code is concerned, the response content type header should provide everything that is needed to deserialize the payload into the appropriate structure. It is true that most languages don't support the notion of a method that can return multiple different types, so some compromise will need to be made on the signature of calling method. If having a precise signature is important, then perhaps using multiple paths is a better option.

@darrelmiller
Copy link
Member Author

@ePaul I agree that some discussion of how form-data can be described by schemas is important. But the discussion of how non-JSON data can be described is also bigger than just forms. Hopefully we can address that subject very soon.

@fehguy
Copy link
Contributor

fehguy commented Aug 19, 2016

@OAI/tdc let's get your input on this

"representations" : {
"application/json" : {
"schema": {
"type": "array",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indentation looks weird when rendered via Markdown.

@whitlockjc
Copy link
Member

How do representations support the void response, where there is no body?

"status":
"description" : "Updated status of the pet",
"type": "string"
},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like we're going from a flat array of parameters to an object with those fields. Is the intention that we treat the object as an array of form variables?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is my current proposal for mapping form-style key/value pairs into JSON schema.

@darrelmiller
Copy link
Member Author

@whitlockjc I would represent void responses by not including a representations object.

@darrelmiller darrelmiller changed the title Issue 721 - Representation objects for describing request/response payloads Issue 721 - Content objects for describing request/response payloads Sep 10, 2016
fehguy added a commit that referenced this pull request Sep 29, 2016
darrelmiller added a commit that referenced this pull request Sep 29, 2016
updated #761 for naming consistency
# Conflicts:
#	versions/3.0.md
@darrelmiller darrelmiller merged commit 827f76a into OpenAPI.next Sep 29, 2016
@fehguy fehguy deleted the issue-721 branch October 20, 2016 17:12
AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019
AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019
AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019
Issue 721 - Content objects for describing request/response payloads
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants