Fix pagination response and add docu (#196)

The original PR added the wrong field `pagination_parameters` twice, it
should have been `pagination_info` in the response message.

Author: Marenz

RELEASE_NOTES.md

@@ -2,10 +2,16 @@
 
 ## Summary
 
-This is just a minor update that changes the `Dispatch` message structure a bit.
+<!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-* `DispatchDetail` is now `Dispatch`
-* `Dispatch` became `DispatchData`
-* Member part of `Dispatch` is now the new message `DispatchMedatata`
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+
+## New Features
+
+<!-- Here goes the main new features and examples or instructions on how to use them -->
+
+## Bug Fixes
+
+* Fixed pagination fields in the response (`pagination_params` -> `pagination_info`)

proto/frequenz/api/dispatch/v1/dispatch.proto

@@ -521,7 +521,12 @@ message ListMicrogridDispatchesRequest {
   // Sorting options for the result
   SortOptions sort_options = 3;
 
-  // Pagination parameters
+  // Pagination Parameters
+  // page_size: Amount of items to return per page. Should only be provided in the first request.
+  // page_token: Cursor to specify which page to return. Should not be set in the first request.
+  //             Should be populated in subsequent requests by the `next_page_token` found in
+  //             the `pagination_info` in the response.
+  //             The tokens stays valid indefinitely.
   frequenz.api.common.v1.pagination.PaginationParams pagination_params = 4;
 }
 
@@ -530,10 +535,14 @@ message ListMicrogridDispatchesResponse {
   // The dispatches
   repeated Dispatch dispatches = 1;
 
-  // Pagination parameters
-  frequenz.api.common.v1.pagination.PaginationParams pagination_params = 4;
+  // Pagination Info
+  // total_items: Total amount of entries found by the list request.
+  // next_page_token: Token that can be used to request the next page.
+  //                  Will be unset if no further pages exist.
+  frequenz.api.common.v1.pagination.PaginationInfo pagination_info = 2;
 }
 
+
 // Message to create a new dispatch with the given attributes
 message CreateMicrogridDispatchRequest {
   // The microgrid identifier