Re-using model with different required properties

by

In your example, you can use a single model for both GET and POST/PUT, with properties only used in the GET response marked as readOnly. From the spec:

readOnly

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.

The spec would look like:

    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/Cat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/Cat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    properties:
      id:
        type: integer
        readOnly: true
      name:
        type: string
      breed:
        type: string
    required:
      - name
      - breed

This means you must PUT the name and breed:

{
  "name": "Puss in Boots",
  "breed": "whatever"
}

and GET /cats/{id} must return the name and breed and may also return the id:

{
  "name": "Puss in Boots",
  "breed": "whatever",
  "id": 5
}

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to specify if a field is optional or required in OpenAPI/Swagger?
  3. How to return an array of objects in SwaggerHub?
  4. How to document dynamic query parameter names in OpenAPI (Swagger)?
  5. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  6. How to define a property that can be string or null in OpenAPI (Swagger)?
  7. Swagger schema properties ignored when using $ref – why?
  8. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  9. Swagger 2.0: Multiple Path objects with different paths but same request and response
  10. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  11. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  12. Swagger: wildcard path parameters
  13. How to define an optional parameter in path using swagger
  14. Swagger: “equivalent path already exists” despite different parameters
  15. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  16. How not to copy-paste 3 generic error responses in almost all paths?
  17. How to define global parameters in OpenAPI?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. Swagger Inheritance and Composition
  21. Swagger/OpenAPI mock server
  22. Swagger: map of
  23. Use object type query param in swagger documentation
  24. Swagger complex response model with dynamic key value hash maps
  25. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  26. OpenAPI query string parameter with list of objects
  27. OpenAPI path/query parameters nested structure serialization
  28. Combining defintions in Swagger docs
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Leave a Comment