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

Support Schemas for Request Body / Query Params #127

Closed
ewalker11 opened this issue May 14, 2017 · 2 comments

Comments

@ewalker11
Copy link

commented May 14, 2017

The marshmallow plugin already nicely supports schemas for response bodies, but it would be nice if it could also support schemas for request bodies/query params. I have a PR that could support this, but wanted to get feedback on the format. Here's what I was thinking:

Body:

This would operate similarly to the existing response schema handling, where the schema would get replaced by a $ref if found in the definitions.

post:
    description: Add your favorite pet
    parameters:
        - name: body
          schema: PetSchema
    responses:
        200:
            description: The pet that was added
            schema: PetSchema

Result:

{
  "paths": {
    "/pet": {
      "post": {
        "description": "Add your favorite pet",
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "schema": {
              "$ref": "#/definitions/Pet"
            }
          }
        ],
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Pet"
            },
            "description": "The pet that was added"
          }
        }
      }
    }
  }
}

Query params:

This gets a little weird, since OpenAPI doesn't really support refs for query params AFAICT. What I was thinking is that we'd iterate through all the fields in the schema and make each one a parameter.

get:
    description: Search by pet id
    parameters:
        - name: query
          schema: PetSearchSchema
    responses:
        200:
            description: The pet that was found with the search
            schema: PetsSchema

Result:

{
  "paths": {
    "/pet": {
      "get": {
        "description": "Search by pet id",
        "parameters": [
          {
            "type": "string",
            "name": "pet_id",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Pet"
            },
            "description": "The pet that was found with the search"
          }
        }
      }
    }
  }
}
@yoichi

This comment has been minimized.

Copy link
Collaborator

commented Jun 30, 2017

In your examples, "name" is specified in an element of "parameters" and it will not be carried over to result. It may cause confusion if there are query parameter named "query" or "body".
I think it is better to specify "in" in docstrings instead.

yoichi added a commit to yoichi/apispec that referenced this issue Jul 9, 2017

Generate parameters specification by marshmallow schema
Implement the proposal in
marshmallow-code#127

* generate single entry by "in: body"
* generate array of primitive types otherwise
@ewalker11

This comment has been minimized.

Copy link
Author

commented Jul 29, 2017

@yoichi I'm good with in instead of name 👍

@sloria sloria closed this Aug 9, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.