typespec1-5  Exercise 1: A Documented Ticket Service
=========================================================

ticket.tsp (TypeSpec 1.17.0; OpenAPI 3.1.0):

  import "@typespec/http";

  using Http;

  /** Sells tickets for events. */
  @service(#{ title: "Ticket Service" })
  namespace Tickets;

  /** A ticket for one seat at one event. */
  @example(#{ id: "t_9", code: "AB12CD", seat: "F14", price: 35.5 })
  model Ticket {
    /** Assigned when the ticket is sold. */
    id: string;

    /** Six upper-case letters and digits, printed on the ticket. */
    @pattern("^[A-Z0-9]{6}$")
    code: string;

    /** Row letter and seat number, such as F14. */
    @minLength(2)
    @maxLength(4)
    seat: string;

    /** Price in pounds. Free tickets are not sold through this service. */
    @minValueExclusive(0)
    price: float64;
  }

  @route("/tickets")
  interface TicketOps {
    /** Look up a ticket by its id. */
    @summary("Read a ticket")
    @route("{id}") @get read(
      /** The ticket's id. */
      @path id: string,
    ): Ticket;
  }

The generated OpenAPI (paths and components):

  paths:
    /tickets/{id}:
      get:
        operationId: TicketOps_read
        summary: Read a ticket
        description: Look up a ticket by its id.
        parameters:
          - name: id
            in: path
            required: true
            description: The ticket's id.
            schema:
              type: string
        responses:
          '200':
            description: The request has succeeded.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Ticket'
  components:
    schemas:
      Ticket:
        type: object
        required:
          - id
          - code
          - seat
          - price
        properties:
          id:
            type: string
            description: Assigned when the ticket is sold.
          code:
            type: string
            pattern: ^[A-Z0-9]{6}$
            description: Six upper-case letters and digits, printed on the ticket.
          seat:
            type: string
            minLength: 2
            maxLength: 4
            description: Row letter and seat number, such as F14.
          price:
            type: number
            format: double
            description: Price in pounds. Free tickets are not sold through this service.
            exclusiveMinimum: 0
        description: A ticket for one seat at one event.
        examples:
          - id: t_9
            code: AB12CD
            seat: F14
            price: 35.5

CHECKING THE OUTPUT AGAINST THE BRIEF
  Six upper-case characters : pattern ^[A-Z0-9]{6}$ on code (letters and digits, as the doc comment says)
  Seat 2 to 4 characters    : minLength 2, maxLength 4
  Price above zero          : exclusiveMinimum: 0 (a number, because this is 3.1; in 3.0 it would be minimum: 0 plus exclusiveMinimum: true)
  Every property documented : each has a description, from its doc comment
  Example                   : examples: on the Ticket schema
  Summary                   : 'Read a ticket' on the operation, with its description kept separate
  The path parameter's own description is in the parameters list ('The ticket's id.')
One thing the brief did not ask for and I did not do: the id has no validation rule. That is deliberate (the service makes up the ids), but the contract does not say what they look like, and a client cannot tell.

WHY THIS WORKS AS AN ANSWER
---------------------------
Each requirement in the brief has one decorator and one visible line of output. Reading the YAML and ticking the requirements off is the review, because the compiler accepts a model with no documentation at all.