Skip to content

Conversation

cl11e
Copy link

@cl11e cl11e commented Apr 22, 2025

Description

This PR introduces significant improvements to API client macros, adding documentation support and more robust type generation while maintaining backward compatibility.

Impact:

  • Self-documenting API endpoints
  • Reduced boilerplate for result types
  • Better IDE support via visible docs
  • More maintainable client code

Documented Macro Inputs

1. api_endpoint!

  • Endpoint struct with lifetime parameters
  • EndpointSpec trait implementation
  • Proper HTTP method binding
  • Path formatting with variables
  • Request body serialization (when needed)
  • Added support for /// doc comments in api_endpoint!
  • Preserves documentation on generated structs
api_endpoint!(
    /// Acknowledge + Retry messages from a Queue.
    /// <https://developers.cloudflare.com/api/resources/queues/subresources/messages/methods/ack/>
    POST,
    AckRetry => AckQueueResults,
    "accounts/{}/queues/{}/messages/ack";
    account_id,
    queue_id;
    params: ActionMessage
);

2. api_results!

  • Generates a {Name}Results struct that encapsulates the typed payload within the results field of an ApiResponse wrapper.
  • Dedicated macro for result type generation
  • Supports field-level documentation
  • Enforces snake_case serialization
// gen `AckQueueResults`
api_results!(AckQueue {
    /// The number of messages that were succesfully acknowledged.
    ackCount: u64,
    /// The number of messages that were succesfully retried.
    retryCount: u64,
    warnings: Vec<String>,
});
// gen `PullQueueResults`
api_results!(PullQueue {
    id: String,
    attempts: i64,
    body: String,
    /// An ID that represents an "in-flight" message that has been pulled from a Queue. You must hold on to this ID and use it to acknowledge this message.
    lease_id: String,
});

3. api_gen!

  • macro that generates trivial trait implementations for ApiResult
api_gen!(PullQueueResults);

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant