Response Structure

This page explains how the serverpod_swagger generator creates response definitions for each endpoint operation in the OpenAPI specification.

Generated Responses

Every operation in the generated spec includes exactly three responses:

Status CodeDescriptionContent
200Successful operationJSON schema of the return type (if not void)
400Bad requestNo content schema
500Internal server errorNo content schema

Example: Endpoint with Return Type

Given this Serverpod endpoint method:

user_endpoint.dart
1class UserEndpoint extends Endpoint {
2  Future<User> getUser(Session session, int id) async {
3    // ...
4  }
5}

The generator produces a response with the return type schema:

apispec.json (excerpt)
1{
2  "responses": {
3    "200": {
4      "description": "Successful operation",
5      "content": {
6        "application/json": {
7          "schema": {
8            "$ref": "#/components/schemas/User"
9          }
10        }
11      }
12    },
13    "400": {
14      "description": "Bad request"
15    },
16    "500": {
17      "description": "Internal server error"
18    }
19  }
20}

Example: Void Return Type

When an endpoint returns void or Future<void>, the 200 response has no content schema:

apispec.json (excerpt)
1{
2  "responses": {
3    "200": {
4      "description": "Successful operation"
5    },
6    "400": {
7      "description": "Bad request"
8    },
9    "500": {
10      "description": "Internal server error"
11    }
12  }
13}

Example: List Return Type

When an endpoint returns a list, the schema uses the array type:

user_endpoint.dart
1Future<List<User>> listUsers(Session session) async {
2  // ...
3}
apispec.json (excerpt)
1{
2  "200": {
3    "description": "Successful operation",
4    "content": {
5      "application/json": {
6        "schema": {
7          "type": "array",
8          "items": {
9            "$ref": "#/components/schemas/User"
10          }
11        }
12      }
13    }
14  }
15}

Request Body and Required Fields

For POST, PATCH, and DELETE operations, endpoint parameters are placed in a JSON request body. Non-nullable parameters are included in the required array:

user_endpoint.dart
1Future<User> createUser(Session session, String name, String email, int? age) async {
2  // ...
3}
apispec.json (excerpt)
1{
2  "requestBody": {
3    "required": true,
4    "content": {
5      "application/json": {
6        "schema": {
7          "type": "object",
8          "properties": {
9            "name": { "type": "string" },
10            "email": { "type": "string" },
11            "age": { "type": "integer", "format": "int64" }
12          },
13          "required": ["name", "email"]
14        }
15      }
16    }
17  }
18}

Note that age is nullable (int?) and therefore is not in the required array.

Adding Custom Examples

The generator does not produce example values automatically. If you need examples in your spec, you can edit apispec.json directly after generation. Use --update on subsequent runs to preserve your manual edits when changing auth or base URL settings.

Next Steps