Remove duplicate title heading for generated docs (#4666)
This commit is contained in:
Timothee Guerin
GitHub
Родитель
12c67ef552
Коммит
58bd612c17
|
|
@ -2,8 +2,6 @@
|
|||
title: Guide
|
||||
---
|
||||
|
||||
# JSON Schema files and references
|
||||
|
||||
When a TypeSpec data type has the `@jsonSchema` decorator or is declared inside a namespace with that decorator, it is considered a _JSON Schema type_.
|
||||
|
||||
By default, this emitter will produce one JSON Schema file per JSON Schema type. The file defines an `$id` metadata keyword based on the TypeSpec type name and the file format of the schema (for example, `Widget.yaml`). The `$id` can be overridden by using the `@id` decorator.
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.JsonSchema
|
||||
|
||||
### `Json` {#TypeSpec.JsonSchema.Json}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.JsonSchema
|
||||
|
||||
### `@baseUri` {#@TypeSpec.JsonSchema.baseUri}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Emitter
|
||||
|
||||
## Usage
|
||||
|
||||
1. Via the command line
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: OpenAPI3 to TypeSpec
|
||||
---
|
||||
|
||||
# tsp-openapi3 CLI
|
||||
|
||||
:::warning
|
||||
The OpenAPI3 to TypeSpec conversion purpose is a one time conversion to help you get started with TypeSpec.
|
||||
The output can change in future versions of TypeSpec without being considered a breaking change.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Diagnostics
|
||||
---
|
||||
|
||||
# Diagnostics
|
||||
|
||||
The OpenAPI emitter may produce any of the following diagnostic messages.
|
||||
|
||||
<!-- Topics within this section should be ordered alphabetically for easy lookup -->
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Emitter operation
|
||||
---
|
||||
|
||||
# Exploring the Functionality of the OpenAPI Emitter
|
||||
|
||||
The OpenAPI emitter is designed to translate TypeSpec language elements into their corresponding OpenAPI expressions. Here's how it works:
|
||||
|
||||
## Server Details
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.OpenAPI
|
||||
|
||||
### `@oneOf` {#@TypeSpec.OpenAPI.oneOf}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Emitter
|
||||
|
||||
## Usage
|
||||
|
||||
1. Via the command line
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Guide
|
||||
---
|
||||
|
||||
# Understanding the Protobuf Emitter
|
||||
|
||||
TypeSpec includes a built-in emitter (`/protobuf`) that can generate Protocol Buffers specifications from TypeSpec sources. The Protobuf files generated can then be used to create gRPC services or any other tools that are compatible with Protocol Buffers.
|
||||
|
||||
**Please note**: The Protobuf emitter is designed to work with Protocol Buffers 3 (proto3) syntax. Ensure that your workflow (including `protoc` version) supports proto3 to make full use of this emitter.
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.Protobuf
|
||||
|
||||
### `Extern` {#TypeSpec.Protobuf.Extern}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Protobuf
|
||||
|
||||
### `@field` {#@TypeSpec.Protobuf.field}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Emitter
|
||||
|
||||
## Usage
|
||||
|
||||
1. Via the command line
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library and emitter for Protobuf (gRPC)
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: basics
|
|||
title: Creating a TypeSpec Library
|
||||
---
|
||||
|
||||
# Creating a TypeSpec library
|
||||
|
||||
A TypeSpec library is a package that includes TypeSpec types, decorators, emitters or linters. These libraries are [npm packages](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) with some additional TypeSpec-specific metadata and conventions. This guide will walk you through the process of creating a new TypeSpec library, adding types to it, and distributing it on the public npm registry. Further sections will delve into the specifics of creating [decorators](create-decorators.md), [emitters](./emitters-basics.md) and [linters](./linters.md).
|
||||
|
||||
While this guide assumes that you'll be using [TypeScript](https://typescriptlang.org) to develop your library, you can skip the TypeScript-related steps if you prefer to use plain JavaScript.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: create-decorators
|
|||
title: Decorators
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
TypeSpec decorators are implemented as JavaScript functions. The process of creating a decorator can be divided into two parts:
|
||||
|
||||
1. [Declare the decorator signature in TypeSpec](#declare-the-decorator-signature) (optional but recommended)
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: emitter-framework
|
|||
title: Emitter framework
|
||||
---
|
||||
|
||||
# Emitter framework
|
||||
|
||||
:::warning
|
||||
The emitter framework has many issues in its current form and a V2 using a completely different approach is in the works. Use with caution.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: emitter-metadata-handling
|
|||
title: Managing metadata and visibility in REST API emitters
|
||||
---
|
||||
|
||||
# Managing metadata and visibility in REST API emitters
|
||||
|
||||
Ensuring consistent handling of [automatic visibility](../libraries/http/operations.md#automatic-visibility) and [metadata](../libraries/http/operations.md#metadata) by all REST API emitters is crucial. To understand how these features work, please refer to the TypeSpec-author documentation. This guide will help you integrate these features into your own emitter correctly.
|
||||
|
||||
The standard `/rest` library offers a JavaScript API for emitters to interpret APIs written using its decorators. We will focus on the APIs that are specifically relevant to these features.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: emitters
|
|||
title: Emitters
|
||||
---
|
||||
|
||||
# Creating emitters
|
||||
|
||||
TypeSpec emitters are libraries that utilize various TypeSpec compiler APIs to reflect on the TypeSpec compilation process and generate artifacts. The TypeSpec standard library includes emitters for OpenAPI version 3.0, JSON Schema, and Protocol Buffers (Protobuf). However, you might want to emit TypeSpec to a different output format. One of the main advantages of TypeSpec is its ease of use as a single source of truth for all data shapes, and the simplicity of creating an emitter contributes significantly to this.
|
||||
|
||||
## Emitter design
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: linters
|
|||
title: Linters
|
||||
---
|
||||
|
||||
# Linters
|
||||
|
||||
## Linter versus `onValidate`
|
||||
|
||||
A TypeSpec library can provide an `$onValidate` hook, which can be used to validate whether the TypeSpec program is valid according to your library's rules.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Scaffolding templates
|
||||
---
|
||||
|
||||
# Creating a scaffolding template
|
||||
|
||||
TypeSpec offers a scaffolding feature through the `tsp init` command.
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ title: Getting Started with TypeSpec For REST APIs
|
|||
pagination_next: getting-started/getting-started-rest/02-operations-responses # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183
|
||||
---
|
||||
|
||||
# Getting Started with TypeSpec for REST APIs
|
||||
|
||||
## Introduction
|
||||
|
||||
Welcome to our tutorial on using TypeSpec to define REST APIs with HTTP. In this section, we'll introduce you to TypeSpec, help you set up your environment, and cover the basic syntax and structure of TypeSpec. By the end of this section, you'll have a solid foundation to build upon in the subsequent sections.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: 02-operations-responses
|
|||
title: Operations and Responses
|
||||
---
|
||||
|
||||
# Operations and Responses
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll build upon the basics we covered in the previous section. We'll define CRUD operations (Create, Read, Update, Delete) for our Pet Store API and discuss the benefits of using nested namespaces.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Handling Errors
|
||||
---
|
||||
|
||||
# Handling Errors in Your REST API
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll focus on handling errors in your REST API. We'll define error models and demonstrate how to add them as possible responses to your CRUD operations.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Common Parameters
|
||||
---
|
||||
|
||||
# Reusing Common Parameters
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll focus on reusing common parameters in your REST API. Common parameters are parameters that are used across multiple operations. By defining these parameters once and reusing them, we can make our API more consistent, easier to read, and easier to maintain.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Authentication
|
||||
---
|
||||
|
||||
# Adding Authentication to Your REST API
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll focus on adding [authentication](../../libraries/http/authentication) to your REST API. We'll introduce the `@useAuth` decorator, show how to enforce authentication on specific operations, and provide an example using Bearer authentication.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Versioning
|
||||
---
|
||||
|
||||
# Versioning
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll focus on implementing versioning in your REST API. Versioning allows you to manage changes to your API over time without breaking existing clients. We'll introduce the `@versioned` decorator, show how to define versions with enums, and demonstrate how to use the `@added` decorator to specify version-specific models and operations.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Custom Response Models
|
||||
---
|
||||
|
||||
# Custom Response Models
|
||||
|
||||
## Introduction
|
||||
|
||||
In this section, we'll focus on creating custom response models and demonstrate how to use them in your API operations. We'll also incorporate predefined response models from the TypeSpec HTTP library.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Conclusion
|
||||
---
|
||||
|
||||
# Conclusion
|
||||
|
||||
## Recap of Key Concepts
|
||||
|
||||
Throughout this tutorial, we've covered a wide range of topics to help you build a comprehensive REST API using TypeSpec. Here's a brief recap of the main concepts we explored:
|
||||
|
|
|
|||
|
|
@ -3,6 +3,4 @@ id: getting-started
|
|||
title: Getting Started
|
||||
---
|
||||
|
||||
# Getting started with TypeSpec
|
||||
|
||||
- [Get started with TypeSpec for REST](./getting-started-rest/01-setup-basic-syntax.md)
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: TypeSpec For OpenAPI Developer
|
||||
---
|
||||
|
||||
# TypeSpec for the OpenAPI developer
|
||||
|
||||
This guide is an introduction to TypeSpec using concepts that will be familiar to developers
|
||||
that either build or use API definitions in OpenAPI v2 or v3.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: cli
|
|||
title: Cli usage
|
||||
---
|
||||
|
||||
# Usage
|
||||
|
||||
See full usage documentation by typing `tsp --help`:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Configuration
|
||||
---
|
||||
|
||||
# Compiler and library configurations
|
||||
|
||||
The TypeSpec compiler and libraries can be configured either via a [configuration file](#configuration-file) or command line flags.
|
||||
|
||||
## Configuration file
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Tracing
|
||||
---
|
||||
|
||||
# Tracing
|
||||
|
||||
The TypeSpec Compiler, by default, builds without any debug information. The standard output is minimal, only including any `warning` or `error` diagnostics that occur during the compilation process.
|
||||
|
||||
However, the compiler does collect additional information that can be accessed using the `--trace` command-line interface (CLI) flag.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: faq
|
|||
title: FAQ
|
||||
---
|
||||
|
||||
# Frequently Asked Questions (FAQ)
|
||||
|
||||
## I'm getting the error `Cannot find package 'x' imported from 'y'`, but I'm not using this package. Why?
|
||||
|
||||
This issue typically arises when package 'y' has a `peerDependency` on package 'x', and package 'x' hasn't been installed. This can occur if you're using a version of npm that's older than version 7, as these older versions don't automatically install peerDependencies. You would need to install them manually.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: formatter
|
|||
title: Formatter
|
||||
---
|
||||
|
||||
# Formatter
|
||||
|
||||
TypeSpec comes with a built-in formatter. The formatter can be used in different ways:
|
||||
|
||||
- [Via the cli](#via-the-cli)
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: releases
|
|||
title: Releases
|
||||
---
|
||||
|
||||
# Releases
|
||||
|
||||
## Versioning strategy for packages
|
||||
|
||||
TypeSpec is currently in its development phase, and all packages are released with a `0.` major version. Each minor version may introduce some breaking changes to the TypeSpec language, library API, or both. These changes are documented [here](../release-notes).
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Style guide
|
||||
---
|
||||
|
||||
# TypeSpec language style guide
|
||||
|
||||
This guide offers a recommended set of naming conventions to follow when drafting a TypeSpec specification.
|
||||
|
||||
:::info
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ title: Installation
|
|||
slug: /
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
## Requirements
|
||||
|
||||
Install [Node.js 20 LTS](https://nodejs.org/en/download/) and ensure you can run the `npm` command in a command prompt:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: aliases
|
|||
title: Aliases
|
||||
---
|
||||
|
||||
# Aliases
|
||||
|
||||
Aliases are a convenient way to define shorthand for types, especially when dealing with complex expressions. They simplify the syntax but don't have a representation in the type graph. As a result, you can't decorate aliases. If you need to give an alternate name to a model, use [`model is`](./models.md).
|
||||
|
||||
You can define an alias using the `alias` keyword.
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: built-in-types
|
|||
title: Built-in types
|
||||
---
|
||||
|
||||
# Built-in types
|
||||
|
||||
TypeSpec Standard Library provide some built-in types that can be used to build more complex types.
|
||||
|
||||
Built in types are related to each other according to the rules described in [type relations](../language-basics/type-relations.md).
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: decorators
|
|||
title: Decorators
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
Decorators in TypeSpec allow developers to attach metadata to types within a TypeSpec program. They can also be used to compute types based on their inputs. Decorators form the core of TypeSpec's extensibility, providing the flexibility to describe a wide variety of APIs and associated metadata such as documentation, constraints, samples, and more.
|
||||
|
||||
A range of TypeSpec constructs can be decorated, including [namespaces](./namespaces.md), [operations](./operations.md) and their parameters, and [models](./models.md) and their members.
|
||||
|
|
|
|||
|
|
@ -3,11 +3,9 @@ id: documentation
|
|||
title: Documentation
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
Documentation is a vital aspect of any API. TypeSpec offers several ways to document your API, including doc comments and decorators.
|
||||
|
||||
# Approaches to documenting APIs
|
||||
## Approaches to documenting APIs
|
||||
|
||||
TypeSpec provides two primary methods for documenting your API:
|
||||
|
||||
|
|
@ -77,7 +75,7 @@ As shown in the previous example, doc comments can use certain tags to document
|
|||
| `@template` | Document a template parameter | `@template T the resource type` |
|
||||
| `@example` (unofficial) | Show examples | `@example \`model Foo {}\` ` |
|
||||
|
||||
# Comments
|
||||
## Comments
|
||||
|
||||
TypeSpec supports both single-line and multi-line comments. Single-line comments start with `//` and continue until the end of the line. Multi-line comments start with `/*` and continue until the closing `*/` is encountered.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: enums
|
|||
title: Enums
|
||||
---
|
||||
|
||||
# Enums
|
||||
|
||||
Enums, short for enumerations, provide a way for developers to define a collection of named constants. They are useful for documenting the purpose of the code or for establishing a set of distinct scenarios. Enums can be either numeric or string-based. For other data types, consider using [unions](./unions.md).
|
||||
|
||||
## The basics
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Identifiers
|
||||
---
|
||||
|
||||
# Identifiers
|
||||
|
||||
Identifiers are used to name models, enums, properties, and other entities in TypeSpec. An identifier is a sequence of one or more characters that must start with a letter, emoji, underscore, or dollar sign, and be followed by letters, numbers, emoji, underscores, or dollar signs. TypeSpec implements [UAX31-R1b stable identifiers](http://www.unicode.org/reports/tr31/#R1b) with the [emoji profile](http://www.unicode.org/reports/tr31/#Emoji_Profile).
|
||||
|
||||
Examples:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: imports
|
|||
title: Imports
|
||||
---
|
||||
|
||||
# Importing files and libraries in TypeSpec
|
||||
|
||||
Imports are used to include files or libraries into your TypeSpec program. When compiling a TypeSpec file, you specify the path to your root TypeSpec file, typically named "main.tsp". From this root file, any imported files are added to your program. If a directory is imported, TypeSpec will search for a `main.tsp` file within that directory.
|
||||
|
||||
The path specified in the import must either start with `"./"` or `"../"`, or be an absolute path. The path should either point to a directory, or have an extension of either ".tsp" or ".js". The examples below illustrate how to use imports to assemble a TypeSpec program from multiple files:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: interfaces
|
|||
title: Interfaces
|
||||
---
|
||||
|
||||
# Interfaces
|
||||
|
||||
Interfaces are useful for grouping and reusing [operations](./operations.md).
|
||||
|
||||
You can declare interfaces using the `interface` keyword. Its name must be an [`identifier`](./identifiers.md).
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: intersections
|
|||
title: Intersections
|
||||
---
|
||||
|
||||
# Intersections
|
||||
|
||||
Intersections in programming define a type that must encompass all the constituents of the intersection. You can declare an intersection using the `&` operator.
|
||||
|
||||
```typespec
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: models
|
|||
title: Models
|
||||
---
|
||||
|
||||
# Models
|
||||
|
||||
Models in TypeSpec are utilized to define the structure or schema of data.
|
||||
|
||||
## Types of models
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: namespaces
|
|||
title: Namespaces
|
||||
---
|
||||
|
||||
# Namespaces
|
||||
|
||||
Namespaces in TypeSpec allow you to group related types together. This organization makes your types easier to locate and helps avoid naming conflicts. Namespaces are merged across files, enabling you to reference any type from anywhere in your TypeSpec program using its namespace.
|
||||
|
||||
## Basics
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: operations
|
|||
title: Operations
|
||||
---
|
||||
|
||||
# Operations
|
||||
|
||||
Operations are essentially service endpoints, characterized by an operation name, parameters, and a return type.
|
||||
|
||||
You can declare operations using the `op` keyword. Its name must be an [`identifier`](./identifiers.md).
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: overview
|
|||
title: Overview
|
||||
---
|
||||
|
||||
# Language Overview
|
||||
|
||||
This document provides a concise overview of the language concepts in TypeSpec. It serves as a quick reference guide rather than an in-depth tutorial.
|
||||
|
||||
## Declarations
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Scalars
|
||||
---
|
||||
|
||||
# Scalars
|
||||
|
||||
Scalars are simple types that don't have any fields. Examples of these include `string`, `int32`, `boolean`, and so on.
|
||||
|
||||
You can declare a scalar by using the `scalar` keyword. Its name must be an [`identifier`](./identifiers.md).
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: templates
|
|||
title: Templates
|
||||
---
|
||||
|
||||
# Templates
|
||||
|
||||
Templates are a powerful tool that allow users to customize certain aspects of a type. Similar to generics in other programming languages, templates define template parameters that users can specify when referencing the type.
|
||||
|
||||
Templates can be applied to:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: type-literals
|
|||
title: Type Literals
|
||||
---
|
||||
|
||||
# Type literals
|
||||
|
||||
When designing APIs, it's common to define the structure of the API in terms of specific literal values. For instance, an operation might return a specific integer status code, or a model member might be one of a few specific string values. It's also useful to pass specific literal values to decorators. TypeSpec supports string, number, and boolean literal values to cater to these needs.
|
||||
|
||||
## String literals
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: type-relations
|
|||
title: Type Relations
|
||||
---
|
||||
|
||||
# Type relations
|
||||
|
||||
## Type hierarchy
|
||||
|
||||
```mermaid
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: unions
|
|||
title: Unions
|
||||
---
|
||||
|
||||
# Unions
|
||||
|
||||
Unions define a type that must be exactly one of several possible variants. There are two types of unions:
|
||||
|
||||
- Union expressions
|
||||
|
|
|
|||
|
|
@ -3,8 +3,6 @@ id: values
|
|||
title: Values
|
||||
---
|
||||
|
||||
# Values
|
||||
|
||||
TypeSpec can define values in addition to types. Values are useful in an API description to define default values for types or provide example values. They are also useful when passing data to decorators, and for template parameters that are ultimately passed to decorators or used as default values.
|
||||
|
||||
Values cannot be used as types, and types cannot be used as values, they are completely separate. However, string, number, boolean, and null literals can be either a type or a value depending on context (see also [scalar literals](#scalar-literals)). Additionally, union and enum member references may produce a type or a value depending on context (see also [enum member & union variant references](#enum-member--union-variant-references)).
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Events
|
||||
|
||||
### `@contentType` {#@TypeSpec.Events.contentType}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library providing events bindings
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Emitter
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
|
||||
TypeSpec HTTP server code generator for JavaScript
|
||||
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Authentication
|
||||
---
|
||||
|
||||
# Configure Http Authentication
|
||||
|
||||
## Configure
|
||||
|
||||
Authentication can be configured using the `@useAuth` decorator on a service namespace, sub-namespace, interface or operation.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Examples
|
||||
---
|
||||
|
||||
# Http Examples
|
||||
|
||||
See [examples docs](../../standard-library/examples.md) for general information about examples.
|
||||
|
||||
## Multiple responses
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Operations
|
||||
---
|
||||
|
||||
# Http Operations
|
||||
|
||||
## Operation verb
|
||||
|
||||
**Default behavior:**
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.Http
|
||||
|
||||
### `AcceptedResponse` {#TypeSpec.Http.AcceptedResponse}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Http
|
||||
|
||||
### `@body` {#@TypeSpec.Http.body}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec HTTP protocol binding
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Linter
|
||||
|
||||
## Usage
|
||||
|
||||
Add the following in `tspconfig.yaml`:
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.OpenAPI
|
||||
|
||||
### `AdditionalInfo` {#TypeSpec.OpenAPI.AdditionalInfo}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.OpenAPI
|
||||
|
||||
### `@defaultResponse` {#@TypeSpec.OpenAPI.defaultResponse}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library providing OpenAPI concepts
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.Rest
|
||||
|
||||
### `ResourceLocation` {#TypeSpec.Rest.ResourceLocation}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Rest
|
||||
|
||||
### `@action` {#@TypeSpec.Rest.action}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec REST protocol binding
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Interfaces and Operations
|
||||
|
||||
## TypeSpec.Rest.Resource
|
||||
|
||||
### `ExtensionResourceCollectionOperations` {#TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations}
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Resource and routes
|
||||
---
|
||||
|
||||
# Resources & routes
|
||||
|
||||
Resources are operations that are grouped in a namespace. You declare such a namespace by adding the `@route` decorator to provide the path to that resource:
|
||||
|
||||
```typespec
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.SSE
|
||||
|
||||
### `SSEStream` {#TypeSpec.SSE.SSEStream}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.SSE
|
||||
|
||||
### `@terminalEvent` {#@TypeSpec.SSE.terminalEvent}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library providing server sent events bindings
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
|
||||
## TypeSpec.Streams
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
|
||||
## TypeSpec.Streams
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
|
||||
TypeSpec library providing stream bindings
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## TypeSpec.Streams
|
||||
|
||||
### `Stream` {#TypeSpec.Streams.Stream}
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Streams
|
||||
|
||||
### `@streamOf` {#@TypeSpec.Streams.streamOf}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library providing stream bindings
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Versioning
|
||||
|
||||
### `@added` {#@TypeSpec.Versioning.added}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library for declaring and emitting versioned APIs
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: Guide
|
||||
---
|
||||
|
||||
# Xml Library
|
||||
|
||||
## Default encoding of scalars
|
||||
|
||||
As in Json we have some [default handling](https://typespec.io/docs/libraries/http/encoding#bytes) of the common scalars like `utcDateTime`
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ toc_min_heading_level: 2
|
|||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## TypeSpec.Xml
|
||||
|
||||
### `@attribute` {#@TypeSpec.Xml.attribute}
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ toc_max_heading_level: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Overview
|
||||
|
||||
TypeSpec library providing xml bindings
|
||||
|
||||
## Install
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: July 2022
|
||||
---
|
||||
|
||||
# Release Notes July 2022 (2022-07-08)
|
||||
|
||||
This release contains **breaking changes**
|
||||
|
||||
- Emitter options normalized to use kebab-case instead of camelCase.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: August 2022
|
||||
---
|
||||
|
||||
# Release Notes August 2022 (2022-08-10)
|
||||
|
||||
This release contains **breaking changes**
|
||||
|
||||
- Operation parameters without decorators
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: September 2022
|
||||
---
|
||||
|
||||
# Release Notes September 2022 (2022-09-07)
|
||||
|
||||
This release contains **breaking changes**:
|
||||
|
||||
- **`Api`**: Remove `Type` suffix
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: October 2022
|
||||
---
|
||||
|
||||
# Release Notes October 2022 (2022-10-12)
|
||||
|
||||
This release contains **breaking changes**:
|
||||
|
||||
- **`TypeSpec`**: Cannot `extends` or `is` a model expression via alias
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: December 2022
|
||||
---
|
||||
|
||||
# Release Notes December 2022 (2022-12-07)
|
||||
|
||||
:::danger
|
||||
This release contains **breaking changes**
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: January 2023
|
||||
---
|
||||
|
||||
# Release Notes January 2023 (2023-01-12)
|
||||
|
||||
:::danger
|
||||
This release contains **breaking changes**
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
title: February 2023
|
||||
---
|
||||
|
||||
# Release Notes February 2023 (2023-02-07)
|
||||
|
||||
:::danger
|
||||
This release contains **breaking changes**
|
||||
:::
|
||||
|
|
|
|||
Некоторые файлы не были показаны из-за слишком большого количества измененных файлов Показать больше
Загрузка…
Ссылка в новой задаче