Troubleshooting

This page provides solutions to common issues you might encounter when using Serverpod Swagger.

Swagger UI Not Loading

Possible Causes and Solutions

1. Missing trailing slash in the URL

Make sure you're accessing Swagger UI with a trailing slash in the URL.

2. Missing or incorrect API specification file

Ensure that the apispec.json file exists in the correct location and is properly formatted.

• Run dart run serverpod_swagger:generate to generate the API specification file.
• Check that the file is created in the project root directory (or the location specified in your configuration).
• Verify that the file contains valid JSON by opening it in a text editor.

3. Incorrect mount path configuration

Ensure that the mountPath parameter in your SwaggerUIRoute configuration matches the URL you're trying to access.

1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    mountPath: '/swagger/', // This must match the URL path you're accessing
5  ),
6);

4. Server not running or accessible

Make sure your Serverpod server is running and accessible at the expected port.

• Check that the server is running by accessing other endpoints or the default Serverpod health check endpoint.
• Verify that there are no firewall or network issues preventing access to the server.

OpenAPI Generation Issues

Possible Causes and Solutions

1. Syntax errors in protocol definitions

Check your protocol definition files for syntax errors or unsupported constructs.

• Run dart analyze to check for syntax errors in your code.
• Fix any reported issues and try generating the specification again.

2. Missing or incorrect annotations

Ensure that your endpoints have the required annotations for proper OpenAPI generation.

1// Missing @Route annotation
2Future<User> getUser(Session session, int id); // This won't be included in the OpenAPI spec
3
4// Correct annotation
5@Route('/users/:id')
6Future<User> getUser(Session session, int id); // This will be included

3. Unsupported data types

Some complex or custom data types might not be automatically handled by the generator.

• Define custom schemas for complex types in an openapi_schemas.yaml file.
• Use simpler data types where possible.
• Check the generator output for warnings about unsupported types.

4. Generator script not finding protocol files

The generator might not be finding your protocol files due to incorrect paths or project structure.

• Ensure your protocol files are in the expected location (usually lib/protocol).
• Run the generator with verbose output to see which files it's processing.
• Check that your project structure follows the standard Serverpod conventions.

Authentication Issues

Possible Causes and Solutions

1. Missing security definitions

Ensure that you've defined the security schemes in your OpenAPI specification.

• Create an openapi_security.yaml file with your security definitions.
• Regenerate the OpenAPI specification to include the security definitions.

2. Incorrect security configuration

Check that your security configuration is correctly formatted and uses supported schemes.

1# Incorrect format (missing type)
2security:
3  - BearerAuth: []
4
5components:
6  securitySchemes:
7    BearerAuth:
8      scheme: bearer
9      bearerFormat: JWT
10
11# Correct format
12security:
13  - BearerAuth: []
14
15components:
16  securitySchemes:
17    BearerAuth:
18      type: http
19      scheme: bearer
20      bearerFormat: JWT

3. CORS issues

Cross-Origin Resource Sharing (CORS) issues might prevent authentication from working properly.

• Ensure your server has appropriate CORS headers configured.
• Check the browser console for CORS-related errors.
• Consider using a CORS proxy for testing if needed.

4. Missing implementation in server code

Remember that Swagger UI only provides the interface for authentication; you need to implement the actual authentication logic in your server code.

• Implement appropriate authentication interceptors in your Serverpod server.
• Ensure your server code validates the authentication credentials properly.

Try-It-Out Feature Not Working

Possible Causes and Solutions

1. CORS issues

Cross-Origin Resource Sharing (CORS) issues are a common cause of problems with the "Try it out" feature.

• Configure your server to allow CORS requests from the Swagger UI origin.
• Add appropriate CORS headers to your server responses.

1// Add CORS headers to your server responses
2session.response.headers.add('Access-Control-Allow-Origin', '*');
3session.response.headers.add('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
4session.response.headers.add('Access-Control-Allow-Headers', 'Origin, Content-Type, X-Auth-Token');

2. Incorrect server URL

The server URL in your OpenAPI specification might be incorrect or inaccessible from the browser.

• Check the server URL in your OpenAPI specification.
• Ensure the URL is accessible from the browser where you're using Swagger UI.
• Update the server URL if needed and regenerate the specification.

3. Authentication issues

If your endpoints require authentication, make sure you've properly authenticated in Swagger UI before using the "Try it out" feature.

• Click the "Authorize" button in Swagger UI and provide the required credentials.
• Check that the authentication is working properly by examining the request headers in the browser's developer tools.

4. Endpoint implementation issues

The endpoint implementation in your server might have issues that prevent it from working properly.

• Test the endpoint directly using a tool like cURL or Postman to verify it works outside of Swagger UI.
• Check your server logs for errors when the endpoint is called.
• Ensure the endpoint implementation matches the OpenAPI specification.

Still Having Issues?

If you're still experiencing problems after trying the solutions above, you can:

• Open an issue on GitHub
• Ask for help in the Serverpod community
• Review the getting started guide