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

fix description for parameters in OpenAPI 3 #223

Merged
merged 5 commits into from Jun 9, 2018

Conversation

@guoli-lyu
Copy link
Contributor

commented Jun 1, 2018

In OpenAPI3, desired output for query parameters is like this:

parameters:
- description: Password
  in: query
  name: password
  required: true
  schema: 
    type: string

However, only properties in, name and required are defined in the top level, while all other properties is moved under property schema, which conflicts with OpenAPI 3 specification.

Current output:

parameters:
- in: query
  name: password
  required: true
  schema: 
    type: string
    description: Password

So before moving all properties to schema, it's reasonable to check for description property and define description in top level of parameter object.

@sloria

This comment has been minimized.

Copy link
Member

commented Jun 1, 2018

Thanks again @guoli-lyu . Can you add a test for this, too? Once that's added, this can be merged.

guoli-lyu added some commits Jun 6, 2018

test(schemas): add additional fields in PetSchema for test
Deprecated and allowEmptyValue keyword is not supported yet. And the
better way maybe is to provide different function of schema2fiels
for different version, respectively.
@guoli-lyu

This comment has been minimized.

Copy link
Contributor Author

commented Jun 6, 2018

I add test for descriptions in parameters and also requestBody, which in OpenAPI 2 is like this:

parameters:
- in: path
  name: name

@sloria

@sloria
Copy link
Member

left a comment

Looks good. Thanks for adding the test. Just some minor revisions to the docs needed. I can make those myself before I merge.

@@ -427,14 +427,21 @@ def fields2parameters(fields, schema=None, spec=None, use_refs=True,
the :class:`Schema <marshmallow.Schema>`.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject
For OpenAPI 3, only "query", "header", "path" or "cookie" is allowed for the location

This comment has been minimized.

Copy link
@sloria

sloria Jun 9, 2018

Member

Minor revisions:

For OpenAPI 3, only "query", "header", "path" or "cookie" are allowed for the location of parameters. "requestBody" is used when fields are in the body.

This function always returns a list, with a parameter for each included field in the :class:`Schema <marshmallow.Schema>`.

@sloria sloria merged commit 1db29fe into marshmallow-code:dev Jun 9, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.