From 5a31e53234579f871560b51386a46c9b64e96458 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABl=20Gangloff?= Date: Sun, 7 Dec 2025 17:01:21 +0100 Subject: [PATCH] docs: add OpenAPI description on the operations --- src/Entity/Connector.php | 18 +++++++++++++++- src/Entity/Domain.php | 8 +++++++ src/Entity/IcannAccreditation.php | 2 ++ src/Entity/Instance.php | 5 ++++- src/Entity/Nameserver.php | 14 ++++--------- src/Entity/Statistics.php | 4 ++++ src/Entity/Tld.php | 12 +++++++++-- src/Entity/User.php | 10 ++++++++- src/Entity/Watchlist.php | 35 +++++++++++++++++++++++++++++++ 9 files changed, 93 insertions(+), 15 deletions(-) diff --git a/src/Entity/Connector.php b/src/Entity/Connector.php index 589cdd6..ae4a902 100644 --- a/src/Entity/Connector.php +++ b/src/Entity/Connector.php @@ -22,19 +22,35 @@ use Symfony\Component\Uid\Uuid; shortName: 'Connector', operations: [ new GetCollection( + openapiContext: [ + 'summary' => 'Retrieve all my Connectors', + 'description' => 'This endpoint allows you to retrieve all connectors linked to your account. These connectors can be linked to Watchlists to automate domain name purchases as soon as they are detected as deleted.', + ], normalizationContext: ['groups' => 'connector:list'], - provider: MyConnectorsProvider::class + provider: MyConnectorsProvider::class, ), new Get( + openapiContext: [ + 'summary' => 'Retrieve one of my connectors', + 'description' => 'This endpoint allows you to retrieve the details of one of the Connectors.', + ], normalizationContext: ['groups' => 'connector:list'], security: 'object.getUser() == user' ), new Post( + openapiContext: [ + 'summary' => 'Create a Connector', + 'description' => 'This endpoint allows you to create a cConnector from the information you provide in the request payload.', + ], normalizationContext: ['groups' => ['connector:create', 'connector:list']], denormalizationContext: ['groups' => 'connector:create'], processor: ConnectorCreateProcessor::class ), new Delete( + openapiContext: [ + 'summary' => 'Delete a Connector', + 'description' => 'This endpoint allows you to delete a Connector. If the Connector is linked to Watchlists, they will not be deleted but will no longer be linked to a Connector.', + ], security: 'object.getUser() == user', processor: ConnectorDeleteProcessor::class ), diff --git a/src/Entity/Domain.php b/src/Entity/Domain.php index aad920a..d1c990d 100644 --- a/src/Entity/Domain.php +++ b/src/Entity/Domain.php @@ -25,6 +25,10 @@ use Symfony\Component\Serializer\Attribute\SerializedName; operations: [ new GetCollection( uriTemplate: '/domains', + openapiContext: [ + 'summary' => 'Reverse Domain lookup', + 'description' => 'This experimental endpoint allows listing domain names that meet a strict condition.', + ], normalizationContext: [ 'groups' => [ 'domain:list', @@ -47,6 +51,10 @@ use Symfony\Component\Serializer\Attribute\SerializedName; ), new Get( uriTemplate: '/domains/{ldhName}', // Do not delete this line, otherwise Symfony interprets the TLD of the domain name as a return type + openapiContext: [ + 'summary' => 'Searching for a Domain', + 'description' => 'This endpoint allows you to perform an RDAP lookup. The query is sent to the relevant registry. When the RDAP response is received, the domain name information is stored in a database for historical and cache purposes.', + ], normalizationContext: [ 'groups' => [ 'domain:item', diff --git a/src/Entity/IcannAccreditation.php b/src/Entity/IcannAccreditation.php index 6844e89..ef0304f 100644 --- a/src/Entity/IcannAccreditation.php +++ b/src/Entity/IcannAccreditation.php @@ -19,6 +19,8 @@ use Symfony\Component\Serializer\Attribute\Groups; new GetCollection( uriTemplate: '/icann-accreditations', openapiContext: [ + 'summary' => 'Retrieve ICANN accreditations', + 'description' => 'This endpoint allows you to list the accreditations of registrars issued by ICANN. It is also possible to search to retrieve only currently valid accreditations.', 'parameters' => [ [ 'name' => 'status', diff --git a/src/Entity/Instance.php b/src/Entity/Instance.php index 801b9a7..a40b953 100644 --- a/src/Entity/Instance.php +++ b/src/Entity/Instance.php @@ -11,8 +11,11 @@ use App\Controller\InstanceController; new Get( uriTemplate: '/config', controller: InstanceController::class, + openapiContext: [ + 'summary' => 'Public configuration of the server', + 'description' => 'This endpoint allows you to retrieve the public configuration of the Domain Watchdog API server. For example, you can retrieve the user authentication configuration.', + ], shortName: 'Configuration', - description: 'Public configuration of the server', read: false ), ] diff --git a/src/Entity/Nameserver.php b/src/Entity/Nameserver.php index de9e246..3486d74 100644 --- a/src/Entity/Nameserver.php +++ b/src/Entity/Nameserver.php @@ -14,18 +14,12 @@ use Symfony\Component\Serializer\Attribute\SerializedName; #[ORM\Entity(repositoryClass: NameserverRepository::class)] #[ApiResource( operations: [ - /* - new GetCollection( - uriTemplate: '/nameservers', - normalizationContext: [ - 'groups' => [ - 'nameserver:list', - ], - ] - ), - */ new Get( uriTemplate: '/nameservers/{ldhName}', + openapiContext: [ + 'summary' => 'Retrieve a DNS server', + 'description' => 'This endpoint allows you to retrieve details of a DNS server. Currently, it is not possible to list the domain names associated with a DNS server via this API.', + ], normalizationContext: [ 'groups' => [ 'nameserver:item', diff --git a/src/Entity/Statistics.php b/src/Entity/Statistics.php index d9eefd9..8478b70 100644 --- a/src/Entity/Statistics.php +++ b/src/Entity/Statistics.php @@ -11,6 +11,10 @@ use App\Controller\StatisticsController; new Get( uriTemplate: '/stats', controller: StatisticsController::class, + openapiContext: [ + 'summary' => 'Statistics of the server', + 'description' => 'This endpoint allows you to retrieve key statistics from this API server. For example, you can retrieve the number of RDAP requests made, the number of domains in the database, the number of domains successfully purchased, the success rate, etc.', + ], shortName: 'Statistics', read: false, ), diff --git a/src/Entity/Tld.php b/src/Entity/Tld.php index 139b758..d615430 100644 --- a/src/Entity/Tld.php +++ b/src/Entity/Tld.php @@ -21,11 +21,19 @@ use Symfony\Component\Serializer\Attribute\Groups; operations: [ new GetCollection( uriTemplate: '/tld', - normalizationContext: ['groups' => ['tld:list']] + openapiContext: [ + 'summary' => 'Retrieve the list of TLDs', + 'description' => 'This endpoint allows you to retrieve the list of TLDs from a database. This list is based on information obtained from IANA and ICANN. It is possible to filter the query according to your criteria (TLD of a certain type, for example).', + ], + normalizationContext: ['groups' => ['tld:list']], ), new Get( uriTemplate: '/tld/{tld}', - normalizationContext: ['groups' => ['tld:item']] + openapiContext: [ + 'summary' => 'Retrieve a TLD', + 'description' => 'This endpoint allows you to retrieve the details of a specific TLD (Top-Level Domain).', + ], + normalizationContext: ['groups' => ['tld:item']], ), ] )] diff --git a/src/Entity/User.php b/src/Entity/User.php index e788ef9..eb1c4ff 100644 --- a/src/Entity/User.php +++ b/src/Entity/User.php @@ -27,13 +27,21 @@ use Symfony\Component\Validator\Constraints as Assert; new Get( uriTemplate: '/me', controller: MeController::class, + openapiContext: [ + 'summary' => 'Retrieve the current user\'s details', + 'description' => 'This endpoint allows you to retrieve the details of the current user.', + ], normalizationContext: ['groups' => 'user:list'], - read: false + read: false, ), new Post( uriTemplate: '/register', routeName: 'user_register', controller: RegistrationController::class, + openapiContext: [ + 'summary' => 'Register a new user', + 'description' => 'If the server configuration allows it, this endpoint enables the registration of a new user. Depending on the server configuration, a confirmation email may be sent to the provided email address so that the user can verify their email address.', + ], denormalizationContext: ['groups' => ['user:register']], read: false, ), diff --git a/src/Entity/Watchlist.php b/src/Entity/Watchlist.php index 0b0be68..32f55a6 100644 --- a/src/Entity/Watchlist.php +++ b/src/Entity/Watchlist.php @@ -27,6 +27,10 @@ use Symfony\Component\Validator\Constraints as Assert; shortName: 'Watchlist', operations: [ new GetCollection( + openapiContext: [ + 'summary' => 'Retrieve all my Watchlists', + 'description' => 'This endpoint allows you to retrieve the list of your Watchlists.', + ], normalizationContext: [ 'groups' => [ 'watchlist:list', @@ -38,6 +42,10 @@ use Symfony\Component\Validator\Constraints as Assert; ), new GetCollection( uriTemplate: '/tracked', + openapiContext: [ + 'summary' => 'Retrieve tracked domain names', + 'description' => 'This endpoint allows you to retrieve the list of domain names present in your Watchlists. The list does not contain duplicates.', + ], normalizationContext: [ 'groups' => [ 'domain:list', @@ -49,6 +57,10 @@ use Symfony\Component\Validator\Constraints as Assert; provider: MyTrackedDomainProvider::class ), new Get( + openapiContext: [ + 'summary' => 'Retrieve the details of a Watchlist', + 'description' => 'This endpoint allows you to retrieve the details of one of the Watchlists.', + ], normalizationContext: [ 'groups' => [ 'watchlist:item', @@ -65,6 +77,8 @@ use Symfony\Component\Validator\Constraints as Assert; new Get( routeName: 'watchlist_calendar', openapiContext: [ + 'summary' => 'iCal feed of a Watchlist', + 'description' => 'This endpoint allows you to retrieve the iCalendar feed from a Watchlist. This feed contains events that have occurred on your monitored domain names.', 'responses' => [ '200' => [ 'description' => 'Watchlist iCalendar', @@ -85,29 +99,47 @@ use Symfony\Component\Validator\Constraints as Assert; name: 'calendar' ), new Post( + openapiContext: [ + 'summary' => 'Create a Watchlist', + 'description' => 'This endpoint allows you to create a new Watchlist. If the entered domain names are unknown or do not exist, an initial RDAP query will be performed on each of these domain names to establish a baseline. In other words, if you register a long Watchlist with unknown domain names, the query may take some time.', + ], normalizationContext: ['groups' => 'watchlist:list'], denormalizationContext: ['groups' => 'watchlist:create'], processor: WatchlistUpdateProcessor::class, ), new Put( + openapiContext: [ + 'summary' => 'Edit a Watchlist', + 'description' => 'This endpoint allows you to modify a Watchlist.', + ], normalizationContext: ['groups' => 'watchlist:list'], denormalizationContext: ['groups' => ['watchlist:update']], security: 'object.getUser() == user', processor: WatchlistUpdateProcessor::class, ), new Patch( + openapiContext: [ + 'summary' => 'Edit a Watchlist', + 'description' => 'This endpoint allows you to modify a Watchlist.', + ], normalizationContext: ['groups' => 'watchlist:list'], denormalizationContext: ['groups' => ['watchlist:update']], security: 'object.getUser() == user', processor: WatchlistUpdateProcessor::class, ), new Delete( + openapiContext: [ + 'summary' => 'Delete a Watchlist', + 'description' => 'This endpoint allows you to delete a Watchlist.', + ], security: 'object.getUser() == user' ), new Get( routeName: 'watchlist_rss_status', defaults: ['_format' => 'xml'], openapiContext: [ + 'summary' => 'RSS feed of a Watchlist (EPP status)', + 'description' => 'This experimental endpoint allows retrieving the RSS feed of a Watchlist. New entries in the feed correspond to a change in the EPP status of a domain name.', 'responses' => [ '200' => [ 'description' => 'Domain EPP status RSS feed', @@ -131,6 +163,9 @@ use Symfony\Component\Validator\Constraints as Assert; routeName: 'watchlist_rss_events', defaults: ['_format' => 'xml'], openapiContext: [ + 'summary' => 'RSS feed of a Watchlist (events)', + 'description' => 'This experimental endpoint allows retrieving the RSS feed of a Watchlist. New entries in the feed correspond to a change in events for a domain name.', + 'responses' => [ '200' => [ 'description' => 'Domain events RSS feed',