Query
You can also use query parameters within routes with the type Query
. The default type of a query is string
, but you can specify a different type by passing a generic type.
import type { Query } from '@kitajs/runtime';
// /?name=Arthur
export function get(name: Query) {
return `Hello ${name}!`;
}
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"parameters": [
{
"schema": { "type": "string" },
"in": "query",
"name": "name",
"required": true
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "string" } }
}
}
}
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Custom names
You can also use different types to define the format of the query.
import type { Query } from '@kitajs/runtime';
// /?option=true
export function get(option: Query<boolean>) {
return option
? 'You have selected the option'
: "You haven't selected the option";
}
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"parameters": [
{
"schema": { "type": "boolean" },
"in": "query",
"name": "option",
"required": true
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"enum": [
"You didn't select the option",
"You selected the option"
],
"type": "string"
}
}
}
}
}
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Complex types
When defining multiple query parameters, it can be cumbersome to put several parameters with the type Query
. For this, you can use interfaces and types to define the query format.
WARNING
Query
with object types cannot be mixed with simple queries that are not object types.
It’s recommended to use Query
for more complex types and only QueryProp
for simple and direct types.
import type { Query } from '@kitajs/runtime';
interface CreateUserRequest {
name: string;
age: number;
}
// /?name=Arthur&age=20
export function get(query: Query<CreateUserRequest>) {
return `Hello ${query.name}! You are ${query.age} years old.`;
}
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"parameters": [
{
"schema": { "type": "number" },
"in": "query",
"name": "age",
"required": true
},
{
"schema": { "type": "string" },
"in": "query",
"name": "name",
"required": true
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "string" } }
}
}
}
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Learn more about exposing types.
Arrays
Arrays can be defined at the top level with Query
for simple types.
import type { Query } from '@kitajs/runtime';
// /?names[]=foo&names[]=bar
export function get(names: Query<string[]>) {
return `Hello ${names.join(', ')}!`;
}
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"parameters": [
{
"schema": { "items": { "type": "string" }, "type": "array" },
"in": "query",
"name": "names",
"required": true
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "string" } }
}
}
}
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Default values
Default values can be used with Query
for both simple types and complex ones.
import type { Query } from '@kitajs/runtime';
interface CreateUserRequest {
name: string;
}
// /?name=Arthur and /
export function get(name: Query<string, 'name'> = 'Arthur') {
return `Hello ${name}!`;
}
// /?name=Arthur and /
export function post(content: Query<CreateUserRequest> = { name: 'Arthur' }) {
return `Hello ${content.name}!`;
}
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"parameters": [
{
"schema": { "type": "string" },
"in": "query",
"name": "name",
"required": false
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "string" } }
}
}
}
},
"post": {
"operationId": "postIndex",
"parameters": [
{
"schema": { "type": "string" },
"in": "query",
"name": "name",
"required": true
}
],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "string" } }
}
}
}
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44