typespec1-1  Exercise 1: A Book Service
=========================================

Setup (in an empty folder):

  npm init -y
  npm install @typespec/compiler @typespec/http @typespec/openapi3

tspconfig.yaml:

  emit:
    - "@typespec/openapi3"

books.tsp (the compiler's entry file is main.tsp by default; name the file main.tsp, or pass the file name to tsp compile):

  import "@typespec/http";

  using Http;

  @service(#{ title: "Book Service" })
  namespace BookService;

  model Book {
    id: string;
    title: string;
    pages: int32;
  }

  @route("/books")
  interface Books {
    @get list(): Book[];
    @get read(@path id: string): Book;
    @post create(@body book: Book): Book;
  }

Compile with:  npx tsp compile .

Result: the TypeSpec is 19 lines; the generated tsp-output/@typespec/openapi3/openapi.yaml is 67 lines (checked with a line count). The start of the OpenAPI:

  openapi: 3.0.0
  info:
    title: Book Service
    version: 0.0.0
  tags: []
  paths:
    /books:
      get:
        operationId: Books_list
        parameters: []
        responses:
          '200':
  ...

WHY THIS WORKS AS AN ANSWER
---------------------------
The model is declared once and used three times; the generated document references it from the list, read and create operations instead of repeating its fields. Because the Book Service has the same shape as the Widget Service of the chapter (three operations, one model of three properties), the numbers match: 19 lines in, 67 out. The ratio is a rough guide and grows when operations carry errors, query parameters and documentation.