sdkgen

https://sdkgen.github.io
Admin
sdkgen is a tool for designing and implementing feature-rich APIs with minimal effort using a...
Tokens:10,430
Snippets:135
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install SDKGen Globally

Source: https://sdkgen.github.io/cli

Use this command to install the SDKGen CLI globally on your system for easy access.

```bash
npm i -g @sdkgen/cli

```

--------------------------------

### Install SDKGen Locally

Source: https://sdkgen.github.io/cli

Install the SDKGen CLI as a development dependency within your current Node.js project. If installed locally, invoke the CLI using `npx sdkgen`.

```bash
npm i --save-dev @sdkgen/cli

```

--------------------------------

### GET /stores/{storeId}/products/{id}

Source: https://sdkgen.github.io/aprofundando/rest

Retrieves a specific product within a store.

```APIDOC
## GET /stores/{storeId}/products/{id}

### Description
Retrieves a specific product within a store.

### Method
GET

### Endpoint
/stores/{storeId}/products/{id}

### Parameters
#### Path Parameters
- **storeId** (uint) - Required - The ID of the store.
- **id** (uint) - Required - The ID of the product.

### Response
#### Success Response (200)
- **Product?** - The requested Product object, or null if not found.
```

--------------------------------

### GET /me

Source: https://sdkgen.github.io/aprofundando/rest

Retrieves the current user's information.

```APIDOC
## GET /me

### Description
Retrieves the current user's information.

### Method
GET

### Endpoint
/me

### Parameters
#### Headers
- **Authorization** (base64) - Required - The authentication token.

### Response
#### Success Response (200)
- **User** - The User object.
```

--------------------------------

### Using arguments as query parameters

Source: https://sdkgen.github.io/aprofundando/rest

Arguments can also be passed as query parameters in the URL (e.g., `GET /orders?state=open`). Specify these in the `@rest` annotation after the path, and they can be nullable.

```typescript
@rest GET /stores/{storeId}/orders?{state}&{date}
fn getOrders(storeId: uint, state: State?, date: date?): Order[]
```

--------------------------------

### Define a basic REST endpoint function

Source: https://sdkgen.github.io/aprofundando/rest

Start by creating a normal sdkgen function with appropriate arguments, return type, and name. Then, add the `@rest` annotation specifying the HTTP method and path.

```typescript
fn getPostsByUser(userId: uuid, since: datetime?, until: datetime?): Post[]

@rest GET /users/{userId}/posts?{since}&{until}
fn getPostsByUser(userId: uuid, since: datetime?, until: datetime?): Post[]
```

--------------------------------

### GET /stores/{storeId}/orders

Source: https://sdkgen.github.io/aprofundando/rest

Retrieves orders for a specific store, with optional filtering by state and date.

```APIDOC
## GET /stores/{storeId}/orders

### Description
Retrieves orders for a specific store, with optional filtering by state and date.

### Method
GET

### Endpoint
/stores/{storeId}/orders

### Parameters
#### Path Parameters
- **storeId** (uint) - Required - The ID of the store.

#### Query Parameters
- **state** (State?) - Optional - Filter orders by state.
- **date** (date?) - Optional - Filter orders by date.

### Response
#### Success Response (200)
- **Order[]** - An array of Order objects.
```

--------------------------------

### Supported HTTP Methods for REST endpoints

Source: https://sdkgen.github.io/aprofundando/rest

sdkgen supports standard HTTP methods like GET, POST, PUT, DELETE, and PATCH for defining REST endpoints. Choose the method that best suits the action the endpoint performs.

```typescript
@rest GET /status
fn getStatus(): bool
```

```typescript
@rest DELETE /product/{id}
fn deleteProduct(id: uuid)
```

```typescript
@rest POST /product [body {newProduct}]
fn createProduct(newProduct: Product): Product
```

--------------------------------

### GET /users/{userId}/posts

Source: https://sdkgen.github.io/aprofundando/rest

Retrieves a list of posts for a specific user, optionally filtered by date range.

```APIDOC
## GET /users/{userId}/posts

### Description
Retrieves a list of posts for a specific user, optionally filtered by date range.

### Method
GET

### Endpoint
/users/{userId}/posts

### Parameters
#### Path Parameters
- **userId** (uuid) - Required - The ID of the user.

#### Query Parameters
- **since** (datetime?) - Optional - Filter posts since this date.
- **until** (datetime?) - Optional - Filter posts until this date.

### Response
#### Success Response (200)
- **Post[]** - An array of Post objects.
```

--------------------------------

### Inicializar Projeto Node.js e Instalar Dependências

Source: https://sdkgen.github.io/primeiro-projeto

Comandos para inicializar um novo projeto Node.js, instalar TypeScript, o SDKGen CLI e o runtime Node.js, e configurar o TypeScript.

```bash
npm init -y
npm i --save-dev typescript @sdkgen/cli
npm i @sdkgen/node-runtime
npx tsc --init -t esnext
```

--------------------------------

### POST /product

Source: https://sdkgen.github.io/aprofundando/rest

Creates a new product.

```APIDOC
## POST /product

### Description
Creates a new product.

### Method
POST

### Endpoint
/product

### Parameters
#### Request Body
- **newProduct** (Product) - Required - The product data to create.

### Response
#### Success Response (200)
- **Product** - The newly created Product object.
```

--------------------------------

### Create Product Endpoint

Source: https://sdkgen.github.io/aprofundando/rest

This snippet demonstrates how to create a new product using a POST request. The request body is mapped to the `newProduct` argument of the `createProduct` function.

```APIDOC
## POST /products

### Description
Creates a new product with the provided details.

### Method
POST

### Endpoint
/products

### Parameters
#### Request Body
- **newProduct** (NewProduct) - Required - The details of the new product to be created.

### Request Example
```json
{
  "name": "Example Product"
}
```

### Response
#### Success Response (200)
- **id** (uuid) - The unique identifier of the created product.
- **name** (string) - The name of the created product.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "Example Product"
}
```
```

--------------------------------

### Definir Tipos e Funções em sdkgen

Source: https://sdkgen.github.io/

Exemplo de como definir tipos de dados e funções para uma API usando a linguagem sdkgen. Inclui tipos primitivos e definidos pelo usuário, com suporte a listas e opcionais.

```sdkgen
type User {
  id: uuid
  email: string
  name: string
}

fn login(email: string, password: string): User
fn logout()
fn me(): User
```

--------------------------------

### Uso de Enumeração em Tipo Composto com Lista em sdkgen

Source: https://sdkgen.github.io/descrevendo-api

Demonstra como um tipo enumerado pode ser usado como tipo de elemento em uma lista dentro de um tipo composto. Permite que um campo contenha uma coleção de valores de um conjunto predefinido.

```sdkgen
{
  name: string
  skills: enum {
    javascript
    csharp
    go
  }[]
}
```

--------------------------------

### Construir e Executar a Aplicação Node.js

Source: https://sdkgen.github.io/primeiro-projeto

Comandos para compilar o código TypeScript para JavaScript e executar a aplicação Node.js.

```bash
npx tsc
node index.js
```

--------------------------------

### Importar outro arquivo SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Importa definições de outro arquivo SDKGen usando um caminho relativo. O conteúdo do arquivo importado é incluído como se estivesse no arquivo atual.

```sdkgen
import "../user"
```

--------------------------------

### Importing Files

Source: https://sdkgen.github.io/descrevendo-api

Organize your API definitions by importing other .sdkgen files using the 'import' keyword.

```APIDOC
## Importando outros arquivos
import "../user"
```

--------------------------------

### Definição de Tipo Composto em sdkgen

Source: https://sdkgen.github.io/descrevendo-api

Define um objeto composto com campos nomeados e seus respectivos tipos. Campos podem ser de qualquer tipo válido, incluindo opcionais e listas.

```sdkgen
{
  name: string
  age: uint
}
```

--------------------------------

### Generate Code with SDKGen CLI

Source: https://sdkgen.github.io/cli

Use the SDKGen CLI to generate source code for various targets (server or client). Specify the source file, output file, and target name.

```bash
sdkgen <source file> -o <output file> -t <target name>

```

```bash
sdkgen src/api.sdkgen -o api.dart -t flutter

```

--------------------------------

### Definir tipo nomeado simples em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Define um tipo nomeado simples usando a palavra-chave 'type' seguida pelo nome do tipo e seu tipo base. Útil para criar aliases para tipos primitivos.

```sdkgen
type PersonName string
```

--------------------------------

### Definição da API em SDKGen

Source: https://sdkgen.github.io/primeiro-projeto

Define um tipo de dado 'Post' e uma função 'getPost' usando a sintaxe do SDKGen. Esta definição serve como contrato para a API.

```sdkgen
type Post {
  id: uuid
  title: string
  body: string
  createdAt: datetime
  author: {
    name: string
  }
}

fn getPost(id: uuid): Post?

```

--------------------------------

### Definição de Tipo Composto Aninhado em sdkgen

Source: https://sdkgen.github.io/descrevendo-api

Exemplo de um tipo composto aninhado, demonstrando a estrutura de objetos complexos com listas de outros objetos. Útil para representar relacionamentos de dados.

```sdkgen
{
  id: uuid
  name: string
  avatar: url?
  friends: {
    id: uuid
    name: string
  }[]
}
```

--------------------------------

### Definição de Enumeração Compacta em sdkgen

Source: https://sdkgen.github.io/descrevendo-api

Uma forma mais compacta de definir um tipo enumerado, com valores separados por espaços. Funcionalmente idêntico à versão com quebras de linha.

```sdkgen
enum { small medium large }
```

--------------------------------

### Gerar Código TypeScript do Servidor Node.js

Source: https://sdkgen.github.io/primeiro-projeto

Comando para gerar o arquivo TypeScript da API a partir da definição em SDKGen. O arquivo gerado não deve ser editado manualmente.

```bash
npx sdkgen api.sdkgen -o api.ts -t typescript_nodeserver
```

--------------------------------

### Declarar uma função simples em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Declara uma função com nome, argumentos tipados e tipo de retorno. Funções declaradas são expostas pela API.

```sdkgen
fn addNumbers(first: int, second: int): int
```

--------------------------------

### Implementação do Servidor Node.js com SDKGen

Source: https://sdkgen.github.io/primeiro-projeto

Arquivo principal da aplicação Node.js que importa o runtime e a API gerada, implementa a função 'getPost' e inicia o servidor HTTP.

```typescript
import { SdkgenHttpServer } from "@sdkgen/node-runtime";
import { api } from "./api";

api.fn.getPost = async (ctx, { id }) => {
  return {
    id,
    title: "Primeira postagem",
    author: {
      name: "John Doe",
    },
    body: "Lorem ipsum",
    createdAt: new Date(),
  };
};

const server = new SdkgenHttpServer(api, {});
server.listen(8000);

```

--------------------------------

### Check API Compatibility

Source: https://sdkgen.github.io/cli

Utilize the SDKGen CLI to check for breaking changes between two versions of an API definition. Provide the paths to the old and new source files.

```bash
sdkgen compatibility --old <old source file> --new <new source file>

```

```bash
sdkgen compatibility --old api_antiga.sdkgen --new api_nova.sdkgen

```

--------------------------------

### Definição de Enumeração Simples em sdkgen

Source: https://sdkgen.github.io/descrevendo-api

Define um tipo enumerado com um conjunto limitado de valores de string. Útil para representar estados ou categorias fixas.

```sdkgen
enum {
  sent
  received
  failed
}
```

--------------------------------

### Definir tipo nomeado composto em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Define um tipo nomeado composto com campos nomeados e seus respectivos tipos. Permite a criação de estruturas de dados complexas.

```sdkgen
type Person {
  name: string
  age: uint
}
```

--------------------------------

### Definir tipos nomeados com enums em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Define um tipo enumerado (enum) e um tipo nomeado que utiliza este enum. Permite a criação de conjuntos de valores nomeados e tipos que os utilizam.

```sdkgen
type UserType enum {
  guest
  fullUser
  admin
}

type User {
  id: uuid
  type: UserType
  name: string
}
```

--------------------------------

### Add Descriptions to Types and Functions

Source: https://sdkgen.github.io/aprofundando/annotations

Use the @description annotation to add documentation to types, fields, and functions. This documentation appears in generated playgrounds and targets. Descriptions can be multi-line using a backslash.

```typescript
@description Detalhes de um usuário.
type User {
  @description Identificador único.
  id: uuid

  @description Nome de apresentação, escolhido pelo próprio usuário.
  name: string

  @description E-mail já validado do usuário.
  email: string?
}

@description Obtém o usuário atual. Caso não tenha feito login, retornará null.
fn getUser(): User?

```

```typescript
@description Retorna o próximo pedido disponível para execução. Essa função \
pode ser chamada em paralelo por múltiplos clientes. Caso não haja um pedido \
aguardando, a execução irá pausar no servidor até que ou um pedido fique \
disponível ou 2 minutos tenham se passado. Caso tenham passado 2 minutos sem \
um pedido o retorno será `null` e você deve chamar novamente.
fn getNextOrder(): Order?

```

--------------------------------

### Add SDKGen Script to package.json

Source: https://sdkgen.github.io/typescript_nodeserver/intro

Add this script to your package.json to enable generating TypeScript code from your .sdkgen files. Run it using `npm run sdkgen`.

```json
{
  "scripts": {
    "sdkgen": "sdkgen src/api.sdkgen -o src/api.ts -t typescript_nodeserver"
  }
}

```

--------------------------------

### Functions

Source: https://sdkgen.github.io/descrevendo-api

Define API functions with their arguments and optional return types. Functions are the primary way users interact with your API.

```APIDOC
## Funções
fn addNumbers(first: int, second: int): int

fn functionWithOptionalArg(arg: string?)

fn functionWithoutReturn(arg1: int, arg2: bool)
```

--------------------------------

### Definição de Tipo e Função de Exemplo

Source: https://sdkgen.github.io/descrevendo-api

Exemplo de definição de um tipo `User` com campos e um enum, e uma função `getUser` que retorna um `User`.

```typescript
error NotFound

type User {
  id: uuid
  avatar: url?
  name: string
  type: enum {
    guest
    fullUser
    admin
  }
}

fn getUser(id: uuid): User
```

--------------------------------

### Declarar um erro com dados adicionais em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Declara um tipo de erro com campos adicionais para fornecer mais contexto. Esses dados são trafegados para o cliente junto com o erro.

```sdkgen
error InvalidArgument {
  argumentName: string
  reason: string
}

error RetryLater datetime
```

--------------------------------

### Registering a Middleware Function

Source: https://sdkgen.github.io/typescript_nodeserver/middlewares

Use `api.use()` to register a middleware. This function receives the context object and a `next` function. Manipulate `ctx` before calling `next()`, and optionally process the response after `next()` returns.

```typescript
api.use(async (ctx, next) => {
  // Faça qualquer coisa com o `ctx` aqui.
  // O nome da função é `ctx.request.name` e os argumentos `ctx.request.args`.
  const reply = await next();
  // Faça qualquer coisa com a resposta aqui.
  return reply;
});

```

--------------------------------

### Integrate SDKGen with HTTP Server or Cloud Function

Source: https://sdkgen.github.io/typescript_nodeserver/intro

Use the `handleRequest` method from `SdkgenHttpServer` to integrate SDKGen with existing HTTP servers like Express or deploy it as a Cloud Function. This allows SDKGen to manage incoming requests.

```typescript
import { SdkgenHttpServer } from "@sdkgen/node-runtime";
import { createServer } from "http";
import { api } from "./api";

const sdkgenServer = new SdkgenHttpServer(api, {});

// Primeira possibilidade: uso com um servidor HTTP existente:
const httpServer = createServer();
httpServer.on("request", sdkgenServer.handleRequest);
httpServer.listen(8080);

// Segunda possibilidade: uso com uma Cloud Function:
exports.api = sdkgenServer.handleRequest; // Aqui, será criada uma Cloud Function com o nome "api", que funciona normalmente como uma API em sdkgen.

```

--------------------------------

### Múltiplos Spreads e Conflitos de Campos

Source: https://sdkgen.github.io/descrevendo-api

Um tipo pode conter múltiplos spreads. Se um campo existir em múltiplos spreads, a última ocorrência prevalecerá. Spreads sempre substituem campos locais em caso de conflito.

```typescript
type A { foo: int }
type B { foo: string }
type C { bar: int }

type Test1 {
  ...B
  ...A
}

type Test2 {
  ...C
  bar: string
}
```

--------------------------------

### Description Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @description annotation is used to add documentation to functions, types, or fields. This documentation appears in the playground and generated targets, explaining the purpose of the item.

```APIDOC
## @description

This annotation can be placed before functions, types, or fields to add documentation. It explains what a function does or the meaning of a field, and this information will be visible in the playground and in some generated targets.

### Example:
```
@description Details of a user.
type User {
  @description Unique identifier.
  id: uuid

  @description Display name, chosen by the user.
  name: string

  @description User's validated email.
  email: string?
}

@description Gets the current user. If not logged in, will return null.
fn getUser(): User?
```

Multi-line descriptions are supported by adding a `\` character at the end of a line. Duplicate `@description` annotations on the same item are not allowed.
```

--------------------------------

### Using dynamic arguments in the URL path

Source: https://sdkgen.github.io/aprofundando/rest

Include dynamic segments in the URL path by referencing function arguments enclosed in curly braces, e.g., `/product/{id}`. The argument type must be one of the allowed primitive or enum types and cannot be nullable.

```typescript
@rest GET /stores/{storeId}/products/{id}
fn getProduct(storeId: uint, id: uint): Product?
```

--------------------------------

### DELETE /product/{id}

Source: https://sdkgen.github.io/aprofundando/rest

Deletes a specific product by its ID.

```APIDOC
## DELETE /product/{id}

### Description
Deletes a specific product by its ID.

### Method
DELETE

### Endpoint
/product/{id}

### Parameters
#### Path Parameters
- **id** (uuid) - Required - The ID of the product to delete.

### Response
#### Success Response (200)
- **bool** - Indicates if the deletion was successful.
```

--------------------------------

### Declarar um erro simples em SDKGen

Source: https://sdkgen.github.io/descrevendo-api

Declara um tipo de erro nomeado. Erros declarados podem ser lançados pelo servidor e transmitidos ao cliente.

```sdkgen
error InvalidArgument
error NotFound
```

--------------------------------

### Argument Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @arg annotation is used to document function arguments, providing their meaning and usage. It can span multiple lines and must be immediately followed by the argument name and its description.

```APIDOC
## @arg

Similar to `@description`, `@arg` documents the meaning of function arguments. It should be immediately followed by the argument name and its description, and can span multiple lines.

### Example:
```
@description Fetch orders made by the user via ID.
@arg id Unique identifier of the order.
@arg includeCanceled If you wish to include orders that have already been canceled, mark as `true`, otherwise use `false`.
fn getOrder(id: uuid, includeCanceled: bool): Order
```
```

--------------------------------

### Definindo Tipos com Spreads

Source: https://sdkgen.github.io/descrevendo-api

Utilize `...NomeDoTipo` para copiar campos de um tipo existente para outro. Campos de spreads têm prioridade sobre campos locais em caso de conflito.

```typescript
type BasicUser {
  id: uuid
  name: string
}

type User {
  email: string
  ...BasicUser
  friends: BasicUser[]
}
```

```typescript
type BasicUser {
  id: uuid
  name: string
}

type User {
  email: string
  id: uuid
  name: string
  friends: BasicUser[]
}
```

--------------------------------

### Throw an error with additional data

Source: https://sdkgen.github.io/releases

Demonstrates how to throw an error that includes additional data. The data can be of any type and provides context for the error.

```typescript
throw new InvalidArgument("Argumento inválido!", { argumentName: "amount", reason: "Deve ser positivo" });

```

--------------------------------

### Document Function Arguments with @arg

Source: https://sdkgen.github.io/aprofundando/annotations

The @arg annotation documents function parameters. It must be followed by the argument name and its description, which can span multiple lines.

```typescript
@description Buscar pedidos feitos pelo usuário através do ID.
@arg id Identificador único do pedido.
@arg includeCanceled Caso deseje incluir pedidos que já foram cancelados \
marcar como `true`, caso contrário utilize `false`.
fn getOrder(id: uuid, includeCanceled: bool): Order

```

--------------------------------

### Define POST Request with Request Body

Source: https://sdkgen.github.io/aprofundando/rest

Use the `@rest` decorator to define a POST request that accepts a JSON body. The `[body {newProduct}]` syntax maps the `newProduct` argument to the request body.

```typescript
type NewProduct {
  name: string
}

type Product {
  id: uuid
  ...NewProduct
}

@rest POST /products [body {newProduct}]
fn createProduct(newProduct: NewProduct): Product

```

--------------------------------

### Receiving arguments via HTTP Headers

Source: https://sdkgen.github.io/aprofundando/rest

Arguments can be passed through HTTP headers, commonly used for authentication. Define headers in the `@rest` annotation using the `[header Name: {argument}]` syntax. Allowed types are the same as for path and query parameters, and they can be optional.

```typescript
@rest GET /me [header Authorization: {token}]
fn getCurrentUser(token: base64): User
```

--------------------------------

### Errors

Source: https://sdkgen.github.io/descrevendo-api

Declare possible errors that your API can return. This helps clients handle unexpected situations gracefully.

```APIDOC
## Erros
error InvalidArgument
error NotFound

error InvalidArgument {
  argumentName: string
  reason: string
}

error RetryLater datetime
```

--------------------------------

### Anatomy of the @rest annotation

Source: https://sdkgen.github.io/aprofundando/rest

The `@rest` annotation defines the REST endpoint. It includes the HTTP method, the resource path with dynamic arguments, optional query parameters, headers, and the request body.

```typescript
@rest MÉTODO /caminho/do/recurso/com/{arg1}/e/{arg2}?{argNaQuery1}&{argNaQuery2} [header Nome: {header}] [body {argBody}]
```

--------------------------------

### REST Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @rest annotation is a general annotation related to RESTful API considerations. Refer to the REST section for more details.

```APIDOC
## @rest

See REST. This annotation is related to RESTful API configurations.
```

--------------------------------

### Define a simple error type

Source: https://sdkgen.github.io/releases

Use this syntax to define a basic error type without additional data.

```typescript
error InvalidArgument

```

--------------------------------

### Define an error with a primitive type

Source: https://sdkgen.github.io/releases

Shows how to define an error that includes a primitive type, such as an unsigned integer, as additional data.

```typescript
error NoFunds uint?

```

--------------------------------

### Named Types

Source: https://sdkgen.github.io/descrevendo-api

Define custom data types using the 'type' keyword. These can be simple aliases or complex structures with fields.

```APIDOC
## Tipos nomeados
type NomeDoTipo Tipo

type PersonName string

type Person {
  name: string
  age: uint
}

type UserType enum {
  guest
  fullUser
  admin
}

type User {
  id: uuid
  type: UserType
  name: string
}
```

--------------------------------

### Specify Possible Errors with @throws

Source: https://sdkgen.github.io/aprofundando/annotations

Use the @throws annotation to indicate which errors a function might raise. This annotation can be repeated for multiple error types. Unspecified errors are converted to 'Fatal'.

```typescript
error NotFound
error Forbidden
error NoFunds

@throws NotFound
@throws Forbidden
fn getUser(id: uuid)

```

--------------------------------

### Throws Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @throws annotation is used to explicitly declare the errors a function can throw during execution. This improves predictability for clients calling the function. It can be included multiple times for different errors.

```APIDOC
## @throws

Functions can naturally throw errors. In SDKGen, you define possible errors (e.g., `error NotFound`). By default, any function can throw any error, which can make them unpredictable. The `@throws` annotation marks which errors a function can specifically throw. It can be used multiple times.

### Example:
```
error NotFound
error Forbidden
error NoFunds

@throws NotFound
@throws Forbidden
fn getUser(id: uuid)
```

In this example, `getUser` can throw `NotFound` or `Forbidden`. All functions can also throw `Fatal` errors, indicating backend bugs. Unmapped errors are converted to `Fatal` for the client.
```

--------------------------------

### Status Code Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @statusCode annotation can be added to error declarations to specify the HTTP status code that will be used when the error is returned in a REST context.

```APIDOC
## @statusCode

This annotation can be added to error declarations to designate the status code that will be used in the error's return. This only affects endpoints in REST mode.

### Example:
```
@statusCode 404
error NotFound
```
```

--------------------------------

### Define an error with additional data fields

Source: https://sdkgen.github.io/releases

Define an error type that includes additional data fields of any type. This allows for more context when an error is thrown.

```typescript
error InvalidArgument {
  argumentName: string
  reason: string
}

```

--------------------------------

### Define Union Type for Events in SDKGen

Source: https://sdkgen.github.io/releases

Use union types to represent properties that can hold multiple data types, such as a list of events with different structures. This feature is currently experimental and supported in Node.js and Web/TypeScript.

```typescript
type Event enum {
  info(msg: string)
  transaction(id: uuid, value: money, date: datetime, description: string)
  refund(id: uuid)
  ping
}

fn getEvents(): Event[]
```

--------------------------------

### Define Recursive Types for Nested Structures in SDKGen

Source: https://sdkgen.github.io/releases

Declare recursive types to handle arbitrarily nested data structures, such as comments within posts where a comment can contain other comments. This feature can be used in conjunction with union types and is currently experimental.

```typescript
type Post {
  body: string
  authorId: uuid
  comments: Comment[]
}

type Comment {
  body: string
  authorId: uuid
  comments: Comment[]
}
```

--------------------------------

### Hidden Annotation

Source: https://sdkgen.github.io/aprofundando/annotations

The @hidden annotation prevents functions from appearing in the playground or generated client targets. It's useful for deprecating old functions or marking functions intended for internal use or REST-only access. Hidden functions can still be called, especially by older targets.

```APIDOC
## @hidden

By default, all functions are callable in the playground and included in generated client targets. If a function needs to exist but should not be called normally, apply the `@hidden` annotation. Hidden functions will not appear in the playground or generated targets, making it useful for deprecating old functions or marking functions for exclusive REST usage. Note that hidden functions still exist and can be called, especially by older targets. Do not use for security purposes.

### Example:
```
@hidden
fn getUser(): User

fn getUserV2(): UserV2
```
```

--------------------------------

### Hide Functions with @hidden

Source: https://sdkgen.github.io/aprofundando/annotations

Apply the @hidden annotation to functions that should not be exposed in playgrounds or generated client targets. This is useful for deprecating functions or for internal use only.

```typescript
@hidden
fn getUser(): User

fn getUserV2(): UserV2

```

--------------------------------

### Assign Status Codes to Errors with @statusCode

Source: https://sdkgen.github.io/aprofundando/annotations

The @statusCode annotation can be added to error declarations to specify the HTTP status code for REST endpoints.

```typescript
@statusCode 404
error NotFound

```
Tokens:
Raw