[api] APIBuffer: add explicit include, fix stale comment, clarify docs

- Add explicit #include "api_buffer.h" in api_server.h
- Remove stale "swap trick" comment in api_frame_helper.h
- Document that exact-size allocation is intentional (no growth factor)
- Clarify debug_check_bounds_ scope to protobuf write path only

esphome/components/api/api_buffer.h

@@ -26,8 +26,13 @@ inline std::unique_ptr<uint8_t[]> make_buffer(size_t n) {
 /// making the zero-fill pure waste. For the receive buffer, bytes are
 /// overwritten by socket reads.
 ///
+/// Designed for bulk clear/resize/overwrite patterns. grow_() allocates
+/// exactly the requested size (no growth factor) since callers resize to
+/// known sizes rather than appending incrementally.
+///
 /// Safe because: callers always write exactly the number of bytes they
-/// resize for, and debug_check_bounds_ validates writes in debug builds.
+/// resize for. In the protobuf write path, debug_check_bounds_ validates
+/// writes in debug builds.
 class APIBuffer {
  public:
   void clear() { this->size_ = 0; }

esphome/components/api/api_frame_helper.h

@@ -178,7 +178,6 @@ class APIFrameHelper {
     // rx_buf_len_ tracks bytes read so far; if non-zero, we're mid-frame
     // and clearing would lose partially received data.
     if (this->rx_buf_len_ == 0) {
-      // Use swap trick since shrink_to_fit() is non-binding and may be ignored
       this->rx_buf_.release();
     }
   }

esphome/components/api/api_server.h

@@ -2,6 +2,7 @@
 
 #include "esphome/core/defines.h"
 #ifdef USE_API
+#include "api_buffer.h"
 #include "api_noise_context.h"
 #include "api_pb2.h"
 #include "api_pb2_service.h"