Add OpenAPI spec generation via utoipa

Derive ToSchema on all request/response and domain types in
ldk-server-json-models, with #[schema(value_type = String)] overrides
for hex-serialized fields. Define all 36 API path operations in a new
openapi module using utoipa's path macro on stub functions, grouped
by tags (Node, Onchain, Bolt11, Bolt12, Channels, Payments, Peers,
Send, Graph, Crypto, Events). The spec is served at /openapi.json
without authentication, cached via LazyLock.

AI tools were used in preparing this commit.

Author: joostjager

Cargo.lock

@@ -5,3 +5,4 @@ edition = "2021"
 
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
+utoipa = { version = "5", features = ["preserve_order"] }

ldk-server-json-models/Cargo.toml

@@ -8,10 +8,11 @@
 // licenses.
 
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
 /// When HttpStatusCode is not ok (200), the response `content` contains a serialized `ErrorResponse`
 /// with the relevant ErrorCode and `message`
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct ErrorResponse {
 	/// The error message containing a generic description of the error condition in English.
 	/// It is intended for a human audience only and should not be parsed to extract any information
@@ -23,7 +24,9 @@ pub struct ErrorResponse {
 	pub error_code: ErrorCode,
 }
 
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[derive(
+	Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize, ToSchema,
+)]
 pub enum ErrorCode {
 	/// Will never be used as `error_code` by server.
 	UnknownError,

ldk-server-json-models/src/api.rs

@@ -8,11 +8,12 @@
 // licenses.
 
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
 /// An event emitted by the LDK Server to notify consumers of payment lifecycle changes.
 ///
 /// Events are published to the configured messaging system (e.g., RabbitMQ) as JSON.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Event {
 	PaymentReceived(PaymentReceived),
@@ -23,36 +24,36 @@ pub enum Event {
 }
 
 /// PaymentReceived indicates a payment has been received.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct PaymentReceived {
 	/// The payment details for the received payment.
 	pub payment: super::types::Payment,
 }
 
 /// PaymentSuccessful indicates a sent payment was successful.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct PaymentSuccessful {
 	/// The payment details for the successful payment.
 	pub payment: super::types::Payment,
 }
 
 /// PaymentFailed indicates a sent payment has failed.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct PaymentFailed {
 	/// The payment details for the failed payment.
 	pub payment: super::types::Payment,
 }
 
 /// PaymentClaimable indicates a payment has arrived and is waiting to be manually claimed or failed.
 /// This event is only emitted for payments created via `Bolt11ReceiveForHash`.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct PaymentClaimable {
 	/// The payment details for the claimable payment.
 	pub payment: super::types::Payment,
 }
 
 /// PaymentForwarded indicates a payment was forwarded through the node.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct PaymentForwarded {
 	/// The forwarded payment details.
 	pub forwarded_payment: super::types::ForwardedPayment,