External/domain-watchdog
1
0
Fork 0
mirror of https://github.com/maelgangloff/domain-watchdog.git synced 2025-12-17 17:55:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add OpenAPI description on the operations

Browse Source
This commit is contained in:
Maël Gangloff 2025-12-07 17:01:21 +01:00
parent 82992c4be9
commit 5a31e53234
No known key found for this signature in database
GPG Key ID: 11FDC81C24A7F629
9 changed files with 93 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/Entity/Connector.php
View File

@ -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
),

8
src/Entity/Domain.php
View File

@ -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',

2
src/Entity/IcannAccreditation.php
View File

@ -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',

5
src/Entity/Instance.php
View File

@ -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
),
]

14
src/Entity/Nameserver.php
View File

@ -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',

4
src/Entity/Statistics.php
View File

@ -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,
),

12
src/Entity/Tld.php
View File

@ -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']],
),
]
)]

10
src/Entity/User.php
View File

@ -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,
),

35
src/Entity/Watchlist.php
View File

@ -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',