API Platform is an incredibly powerful tool for building APIs in Symfony. One of its standout features is the built-in support for API documentation through Swagger. In this article, we will walk through the process of adding a custom controller endpoint to the Swagger documentation in API Platform.
Understanding the Scenario
Let's consider that you want to create a custom controller that returns some data from your Symfony API. Initially, the code may look something like this:
// src/Controller/CustomController.php
namespace App\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
class CustomController
{
/**
* @Route("/api/custom", methods={"GET"})
*/
public function index(): Response
{
return new Response('Custom Data');
}
}
This code snippet creates a new endpoint /api/custom, but it doesn't automatically show up in your Swagger documentation. Therefore, we need to enhance it by adding annotations to provide proper metadata for Swagger.
Step-by-Step Guide to Adding the Endpoint to Swagger
Step 1: Install Swagger Annotations
Ensure you have the Swagger annotations library installed in your Symfony project. You can do this via Composer:
composer require nelmio/api-doc-bundle
Step 2: Modify Your Controller
You need to annotate your controller method so that Swagger can properly document it. Here's how you can modify your CustomController:
// src/Controller/CustomController.php
namespace App\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use OpenApi\Annotations as OA;
class CustomController
{
/**
* @Route("/api/custom", methods={"GET"})
* @OA\Get(
* path="/api/custom",
* summary="Returns custom data",
* @OA\Response(
* response=200,
* description="A JSON object containing custom data"
* )
* )
*/
public function index(): Response
{
return new Response('Custom Data');
}
}
Step 3: Generate OpenAPI Documentation
Once you have added the OpenAPI annotations, you need to generate the documentation. You can do this by running the following command:
php bin/console api:doc:generate
Step 4: Access the Swagger UI
After generating your documentation, navigate to the Swagger UI endpoint, typically available at /api/doc. Here, you will see your newly added /api/custom endpoint along with the summary and response information.
Practical Example
Let's say your application needs to provide an endpoint that returns user data. Using the example from above, you can modify your CustomController to fetch user information from the database. Here’s how you might implement that:
// src/Controller/UserController.php
namespace App\Controller;
use App\Repository\UserRepository;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;
use OpenApi\Annotations as OA;
class UserController
{
private $userRepository;
public function __construct(UserRepository $userRepository)
{
$this->userRepository = $userRepository;
}
/**
* @Route("/api/users", methods={"GET"})
* @OA\Get(
* path="/api/users",
* summary="Retrieve all users",
* @OA\Response(
* response=200,
* description="A list of users"
* )
* )
*/
public function getAllUsers(): JsonResponse
{
$users = $this->userRepository->findAll();
return new JsonResponse($users);
}
}
In this example, we’ve set up an endpoint to retrieve all users and documented it with OpenAPI annotations to ensure it appears correctly in Swagger.
Conclusion
Adding controller endpoints to Swagger in API Platform is an important step to ensure that your API is self-documenting and easy to use for developers. With the integration of OpenAPI annotations, it’s simple to create clear, concise documentation that helps facilitate API consumption.
For further reading and resources, check out:
By following these steps, you'll be well-equipped to document any additional endpoints you create in your Symfony application!
