Source playground examples from samples

packages/playground-website/package.json

@@ -69,6 +69,7 @@
     "@typespec/playground": "workspace:^",
     "@typespec/protobuf": "workspace:^",
     "@typespec/rest": "workspace:^",
+    "@typespec/samples": "workspace:^",
     "@typespec/sse": "workspace:^",
     "@typespec/streams": "workspace:^",
     "@typespec/versioning": "workspace:^",

packages/playground-website/samples/build.ts

@@ -1,47 +1,14 @@
 // @ts-check
-import { buildSamples_experimental } from "@typespec/playground/tooling";
+import { buildPlaygroundSamples } from "@typespec/samples";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 
-await buildSamples_experimental(packageRoot, resolve(__dirname, "dist/samples.ts"), {
-  "API versioning": {
-    filename: "samples/versioning.tsp",
-    preferredEmitter: "@typespec/openapi3",
-    description: "Learn how to version your API using TypeSpec's versioning library.",
-  },
-  "Discriminated unions": {
-    filename: "samples/unions.tsp",
-    preferredEmitter: "@typespec/openapi3",
-    description: "Define discriminated unions for polymorphic types with different variants.",
-  },
-  "HTTP service": {
-    filename: "samples/http.tsp",
-    preferredEmitter: "@typespec/openapi3",
-    compilerOptions: { linterRuleSet: { extends: ["@typespec/http/all"] } },
-    description: "Build an HTTP service with routes, parameters, and responses.",
-  },
-  "REST framework": {
-    filename: "samples/rest.tsp",
-    preferredEmitter: "@typespec/openapi3",
-    compilerOptions: { linterRuleSet: { extends: ["@typespec/http/all"] } },
-    description: "Use the REST framework for resource-oriented API design patterns.",
-  },
-  "Protobuf Kiosk": {
-    filename: "samples/kiosk.tsp",
-    preferredEmitter: "@typespec/protobuf",
-    description: "Generate Protocol Buffer definitions from TypeSpec models.",
-  },
-  "Json Schema": {
-    filename: "samples/json-schema.tsp",
-    preferredEmitter: "@typespec/json-schema",
-    description: "Emit JSON Schema from TypeSpec type definitions.",
-  },
-  GraphQL: {
-    filename: "samples/graphql.tsp",
-    preferredEmitter: "@typespec/graphql",
-    description: "Generate GraphQL schemas with queries, mutations, and types.",
-  },
+await buildPlaygroundSamples({
+  specsDir: resolve(packageRoot, "../samples/specs"),
+  outputFile: resolve(__dirname, "dist/samples.ts"),
+  relativeTo: packageRoot,
+  defaultEmitter: "@typespec/openapi3",
 });

packages/samples/README.md

@@ -4,6 +4,18 @@ This project has a collection of samples used to demonstrate and test various Ty
 
 It is not published as an npm package.
 
+Samples should teach a distinct TypeSpec concept or realistic workflow. Narrow protocol test
+cases belong in the relevant package test suite instead of this collection.
+
+Each sample directory has a `sample-config.yaml` containing a unique `title` and a
+`description`. Set `playground: false` for samples that require multiple files or are not suitable
+for the playground. A directory config uses `directory: true` and can provide a gallery `label`,
+`order`, or an inherited `playground: false`.
+
+The TypeSpec playground is generated from the eligible samples in this package. A playground
+sample must contain a single `main.tsp`; its nearest `tspconfig.yaml` selects the preferred emitter
+and linter rule set, including inherited configuration.
+
 ```bash
 npm run test    # Check Samples match snapshots
 npm run test:ci # run test same as CI

packages/samples/package.json

@@ -46,6 +46,7 @@
     "@typespec/best-practices": "workspace:^",
     "@typespec/compiler": "workspace:^",
     "@typespec/events": "workspace:^",
+    "@typespec/graphql": "workspace:^",
     "@typespec/html-program-viewer": "workspace:^",
     "@typespec/http": "workspace:^",
     "@typespec/http-server-csharp": "workspace:^",
@@ -57,7 +58,8 @@
     "@typespec/rest": "workspace:^",
     "@typespec/sse": "workspace:^",
     "@typespec/streams": "workspace:^",
-    "@typespec/versioning": "workspace:^"
+    "@typespec/versioning": "workspace:^",
+    "yaml": "catalog:"
   },
   "devDependencies": {
     "@types/node": "catalog:",

packages/samples/specs/authentication/sample-config.yaml

@@ -0,0 +1,3 @@
+title: Authentication
+description: Apply authentication schemes at service, interface, and operation scope.
+playground: false

packages/samples/specs/binary/sample-config.yaml

@@ -0,0 +1,3 @@
+title: Binary data
+description: Model binary request and response payloads.
+playground: false

packages/samples/specs/documentation/sample-config.yaml

@@ -0,0 +1,3 @@
+title: Documentation
+description: Add documentation to TypeSpec declarations and emitted API descriptions.
+playground: false

packages/samples/specs/emitters/graphql/main.tsp

@@ -0,0 +1,46 @@
+import "@typespec/graphql";
+
+using GraphQL;
+
+@schema
+namespace PetStore;
+
+/** A pet in the store. */
+model Pet {
+  id: string;
+  name: string;
+  tag?: string;
+  status: PetStatus;
+}
+
+/** A pet's status in the store. */
+enum PetStatus {
+  Available,
+  Pending,
+  Sold,
+}
+
+/** A toy that belongs to a pet. */
+model Toy {
+  id: string;
+  name: string;
+  pet: Pet;
+}
+
+@query
+op getPet(id: string): Pet | null;
+
+@query
+op listPets(status?: PetStatus, limit?: int32): Pet[];
+
+@query
+op getPetToys(petId: string): Toy[];
+
+@mutation
+op createPet(name: string, tag: string, status: PetStatus): Pet;
+
+@mutation
+op updatePet(id: string, name?: string, status?: PetStatus): Pet | null;
+
+@mutation
+op deletePet(id: string): boolean;

packages/samples/specs/emitters/graphql/sample-config.yaml

@@ -0,0 +1,3 @@
+title: GraphQL
+description: Generate a GraphQL schema with queries, mutations, models, and enums.
+order: 3

packages/samples/specs/emitters/graphql/tspconfig.yaml

@@ -0,0 +1,2 @@
+emit:
+  - "@typespec/graphql"

packages/playground-website/samples/json-schema.tsp → packages/samples/specs/emitters/json-schema/main.tsp

@@ -12,32 +12,29 @@ model Person {
   /** The person's last name. */
   lastName: string;
 
-  /** Age in years which must be equal to or greater than zero. */
-  @minValue(0) age: int32;
+  /** Age in years, which must be zero or greater. */
+  @minValue(0)
+  age: int32;
 
-  /** Person address */
+  /** The person's address. */
   address: Address;
 
-  /** List of nick names */
-  @uniqueItems nickNames?: string[];
+  /** The person's nicknames. */
+  @uniqueItems
+  nickNames?: string[];
 
-  /** List of cars person owns */
+  /** Cars owned by the person. */
   cars?: Car[];
 }
 
-/** Respresent an address */
 model Address {
   street: string;
   city: string;
   country: string;
 }
+
 model Car {
-  /** Kind of car */
   kind: "ev" | "ice";
-
-  /** Brand of the car */
   brand: string;
-
-  /** Model of the car */
   `model`: string;
 }

packages/samples/specs/emitters/json-schema/sample-config.yaml

@@ -0,0 +1,3 @@
+title: JSON Schema
+description: Generate JSON Schema documents from TypeSpec models and constraints.
+order: 2

packages/samples/specs/emitters/json-schema/tspconfig.yaml

@@ -0,0 +1,2 @@
+emit:
+  - "@typespec/json-schema"