docs: [#974] update add key endpoint doc

josecelano · josecelano · commit 04f50e454e6e · 2024-07-30T11:31:17.000+01:00
diff --git a/src/servers/apis/v1/context/auth_key/handlers.rs b/src/servers/apis/v1/context/auth_key/handlers.rs
@@ -75,6 +75,8 @@ pub async fn add_auth_key_handler(
 ///
 /// Refer to the [API endpoint documentation](crate::servers::apis::v1::context::auth_key#generate-a-new-authentication-key)
 /// for more information about this endpoint.
+///
+/// This endpoint has been deprecated. Use [`add_auth_key_handler`].
 pub async fn generate_auth_key_handler(State(tracker): State<Arc<Tracker>>, Path(seconds_valid_or_key): Path<u64>) -> Response {
     let seconds_valid = seconds_valid_or_key;
     match tracker.generate_auth_key(Duration::from_secs(seconds_valid)).await {
diff --git a/src/servers/apis/v1/context/auth_key/mod.rs b/src/servers/apis/v1/context/auth_key/mod.rs
@@ -3,8 +3,8 @@
 //! Authentication keys are used to authenticate HTTP tracker `announce` and
 //! `scrape` requests.
 //!
-//! When the tracker is running in `private` or `private_listed` mode, the
-//! authentication keys are required to announce and scrape torrents.
+//! When the tracker is running in `private` mode, the authentication keys are
+//! required to announce and scrape torrents.
 //!
 //! A sample `announce` request **without** authentication key:
 //!
@@ -22,22 +22,31 @@
 //!
 //! # Generate a new authentication key
 //!
-//! `POST /key/:seconds_valid`
+//! `POST /keys`
 //!
-//! It generates a new authentication key.
+//! It generates a new authentication key or upload a pre-generated key.
 //!
 //! > **NOTICE**: keys expire after a certain amount of time.
 //!
-//! **Path parameters**
+//! **POST parameters**
 //!
 //! Name | Type | Description | Required | Example
 //! ---|---|---|---|---
+//! `key` | 32-char string (0-9, a-z, A-Z) | The optional pre-generated key. | No | `Xc1L4PbQJSFGlrgSRZl8wxSFAuMa21z7`
 //! `seconds_valid` | positive integer | The number of seconds the key will be valid. | Yes | `3600`
 //!
+//! > **NOTICE**: the `key` field is optional. If is not provided the tracker
+//! > will generated a random one.
+//!
 //! **Example request**
 //!
 //! ```bash
-//! curl -X POST "http://127.0.0.1:1212/api/v1/key/120?token=MyAccessToken"
+//! curl -X POST http://localhost:1212/api/v1/keys?token=MyAccessToken \
+//!      -H "Content-Type: application/json" \
+//!      -d '{
+//!            "key": "xqD6NWH9TcKrOCwDmqcdH5hF5RrbL0A6",
+//!            "seconds_valid": 7200
+//!          }'
 //! ```
 //!
 //! **Example response** `200`
diff --git a/src/servers/apis/v1/context/auth_key/routes.rs b/src/servers/apis/v1/context/auth_key/routes.rs
@@ -21,8 +21,12 @@ pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
         .route(
             // code-review: Axum does not allow two routes with the same path but different path variable name.
             // In the new major API version, `seconds_valid` should be a POST form field so that we will have two paths:
-            // POST /key
-            // DELETE /key/:key
+            //
+            // POST /keys
+            // DELETE /keys/:key
+            //
+            // The POST /key/:seconds_valid has been deprecated and it will removed in the future.
+            // Use POST /keys
             &format!("{prefix}/key/:seconds_valid_or_key"),
             post(generate_auth_key_handler)
                 .with_state(tracker.clone())
