search

pyopenapi / pyswagger

An OpenAPI (fka Swagger) client & converter in python, which is type-safe, dynamic, spec-compliant.
MIT License
384 stars 88 forks source link

Parameter that is both required and read-only #81

Closed lanzz closed 8 years ago

lanzz commented 8 years ago

Let's say I have a spec that has a POST /entity endpoint, whose body is #/definitions/Entity. Entity is a schema that's an object with an id key, which is both required and read-only; my intention is that this key is required in responses, but forbidden in requests. This does not seem supported by pyswagger — as long as I have the key in the required list, it will not validate a request that does not have it, even though readOnly: true forbids it in a request.

...
definitions:
  entity:
    type: object
      required:
        id
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
...

Rationale: It is not possible to provide an id when creating an entity, and when updating an entity its id will be provided in the URL and it makes no sense to allow changing the id (i.e. provide one id in the URL and a different id in the body), so there is no legitimate situation where that id will make sense in a request, but it is required to be present in a response body so that unit tests using the API spec will fail if they don't see it there.

mission-liao commented 8 years ago

Hi, I would sorry to say that both 'required' and 'readOnly' for Schema object is not implemented yet in pyswagger, I would include these fix in next release.

I'm a little bit busy these days so can't dig into this issue more deep, but I think a property which is both 'required' and 'readOnly' is kind of conflict, and it seems that the spec says it's not legal, too

Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.

(refer to https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-13)

In your use case, I looked for similar case in issues list of swagger spec, and got this https://github.com/OAI/OpenAPI-Specification/issues/228, and per webron's comment, they discussed more fine grained control, and settle down to current version. IMO, just specify 'readOnly' is enough in your case.

I prefer to implement this behavior: when both 'readOnly' and 'required' are specified, an exception would be raised to let users know this combination is not spec-compliant

mission-liao commented 8 years ago

fix and test is included in latest build, please feel free to reopen this case if not work