typespec1-2  Exercise 1: Reading a Hand-Written OpenAPI Document
=====================================================================

The document (checked: it passes Redocly CLI 2.62.1's structural ruleset):

  openapi: 3.0.0
  info:
    title: Book Service
    version: 1.0.0
  paths:
    /books/{isbn}:
      get:
        operationId: getBook
        parameters:
          - name: isbn
            in: path
            required: true
            schema:
              type: string
          - name: include
            in: query
            required: false
            schema:
              type: string
              enum: [reviews, stock]
        responses:
          '200':
            description: The book.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Book'
          '404':
            description: No such book.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Problem'
      put:
        operationId: replaceBook
        parameters:
          - name: isbn
            in: path
            required: true
            schema:
              type: string
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        responses:
          '204':
            description: Replaced.
  components:
    schemas:
      Book:
        type: object
        required: [isbn, title]
        properties:
          isbn:
            type: string
          title:
            type: string
          subtitle:
            type: string
            nullable: true
          pages:
            type: integer
            format: int32
      Problem:
        type: object
        required: [message]
        properties:
          message:
            type: string

ANSWERS
(a) GET /books/{isbn}: the path is /books/{isbn} with the method get, for example GET /books/9780141036144. (The operationId is getBook.)
(b) The path parameter isbn (in: path, required: true). The query parameter include is required: false, so optional; it accepts only 'reviews' or 'stock'. The PUT operation also requires its body (requestBody required: true) and the isbn path parameter.
(c) A body of the Problem schema: an object with one required string property, message. Its description is "No such book."
(d) subtitle is OPTIONAL (it is not in Book's required list, which holds only isbn and title) and NULLABLE (nullable: true, an OpenAPI 3.0 keyword), so a client may omit it or send null. A client may also see it absent or null from the server.
(e) ONE place describes the shape of a Book: the Book schema under components/schemas. It is used by $ref in two places: the 200 response of GET and the request body of PUT.

WHY THIS WORKS AS AN ANSWER
---------------------------
Each answer is a lookup of one part of the document: the path and method give the call, 'required' decides what a client must send, the responses by status code give the outcomes, and the schema's required list and nullable keyword say what a property must be. (Answer (e) shows the value of $ref: one definition, referenced twice. Note that PUT has no error responses at all: the lint rule from the chapter would flag that.)