Open lmmarsano opened 3 years ago
If the Content-Disposition will be manually passed in by devs, how about setting it as type string in parameter.schema.type and set required to true in parameter.required. You could also add a regex pattern in parameter.schema.pattern that must pass for the value of Content-Disposition that describes the filename value as a string with length > 0.
Don't forget to include the body description like so. In openapi-generator in the python client. We have a spec like this:
/fake/uploadDownloadFile:
post:
tags:
- fake
summary: uploads a file and downloads a file using application/octet-stream
description: ''
operationId: uploadDownloadFile
responses:
'200':
description: successful operation
content:
application/octet-stream:
schema:
type: string
format: binary
description: file to download
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
description: file to upload
This doesn't match the request, however.
It's multipart/form-data
.
I'm trying to follow the discussion on specifying headers for those.
The header, Content-Disposition
, is standard.
However, the spec needs to say the parameter, filename
, is required.
I'm thinking the parameter
object for the header would need some combination of style
matrix
and schema
type
object
.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
profileImage:
type: string
format: binary
encoding:
profileImage: # Property name
contentType: application/octet-stream
headers: # Custom headers
Content-Disposition:
description: part's filename
style: matrix
explode: true
schema:
type: object
required:
- form-data
- name
- filename
properties:
form-data:
const: ''
name:
description: part name
type: string
filename:
description: name of file to be created
type: string
RFC 6570 says
If there is an explode modifier, expansion consists of appending each pair that has a defined value as either "name=value" or, if the value is the empty string and the expression type does not indicate form-style parameters (i.e., not a "?" or "&" type), simply "name".
However, this will put a ;
before form-data
, which is incorrect.
Is there something like path templating for headers?
@lmmarsano unfortunately, there's no clear mapping from schemas or parameter styles into HTTP headers, in part because the syntax is pretty inconsistent across different headers. I think the best you could do would be to treat it as a string and use a regex 😕
This issue has been labeled with No recent activity
because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.
@handrews While I agree it's a challenge, it's not entirely inconsistent. The http specification defines a set of rules for the bulk of cases.
,
except for set-cookie
Regex complexity to account for these rules can be considerable. A regex-only solution may often force us to choose between
For clearer, more maintainable specs, I wonder about interest in making the language more aware of the http spec on headers.
While I understand OpenAPI specs largely serve http APIs with JSON payloads, the introduction states it's for http APIs generally, and this seems the logical place for rules in the http spec.
If the interest exists, I also wonder how we might best approach that
@lmmarsano I had actually been thinking about leveraging the rules for the common cases (RFCs 8941 and 9110) and having an extension registry for mechanisms to support more unusual cases.
We can keep discussing headers here to see if there is something that might fit in OAS 3.2 (possibly leveraging the registries).
For the bigger-picture questions of modularity and extension, I would recommend looking at the Moonwalk discussions, where we are discussing breaking changes for the next major OAS release.
Cool, I didn't know about moonwalk.
I'm seeing approaches suggested here overlapping with the inclusion principle, reuse of internet standards, and parameterSchema
.
Based on the participation guidelines, a draft feature in the registry you suggested makes sense.
RFC 8941 is stricter and more structured, so it might be preferable.
retry-after
, so I imagine API authors wanting to represent such fields. While the http core production for http dates appears to be absent from the structured fields spec, the core spec states that members containing ,
ought to be delimited (probably by ”
): the stricter specification identifies such values as strings. Would defining a JSON schema format for http date be appropriate here?For HTTP dates, yeah we'd need to add a format
value to the registry, probably.
I think that RFC 8941 would be handled one way (with one set of format
values as needed), and the "common rules" in RFC 9110 would be handled another. They're similar, but we'd want to make a distinction because of various subtleties. That might include not worrying about the distinction between quoted strings and tokens for 9110, but making that distinction for 8941.
This would be for 3.2 (at the earliest), so there's some time to think about this while we focus on getting 3.0.4 and 3.1.1 out the door.
For example, as described in the guide, in a request such as
how would a spec state that the
filename
parameter in headerContent-Disposition
is required and explain special usage in a description? RFCs state that the filename parameter is optional. It's not clear how to express parameters for a header object.