Refactor docs (#56)

README.md

@@ -1,30 +1,27 @@
 # <img src="website/static/img/logo.png" width="80" height="80"> gRPC Starter [![Build](https://img.shields.io/github/actions/workflow/status/DanielLiu1123/grpc-starter/build.yml?branch=main)](https://github.com/DanielLiu1123/grpc-starter/actions) [![Maven Central](https://img.shields.io/maven-central/v/io.github.danielliu1123/grpc-starter-dependencies?versionPrefix=3.)](https://central.sonatype.com/artifact/io.github.danielliu1123/grpc-starter-dependencies) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[gRPC](https://grpc.io/) is an RPC framework with robust features like high performance, 
-multi-language support, concise service definitions, and streaming. 
-It is an ideal choice for building scalable and efficient microservice systems.
+[gRPC](https://grpc.io/) is a high-performance RPC framework that supports multiple languages, concise service definitions, and streaming. It is an ideal choice for building scalable and efficient microservice systems.
 
-This project provides out-of-the-box, highly extensible Spring Boot starters for gRPC ecosystem.
-Make the integration of Spring Boot and gRPC feel seamless and native.
+This project provides out-of-the-box, highly extensible Spring Boot starters for the gRPC ecosystem, making the integration of Spring Boot and gRPC seamless and native.
 
 ## Features
 
-***Core:***
+### Core:
 
-- Dependencies management for gRPC related libraries
+- Dependency management for gRPC-related libraries
 - gRPC server autoconfiguration
     - [Exception handling](https://danielliu1123.github.io/grpc-starter/docs/server/exception-handing)
     - [Health check](https://danielliu1123.github.io/grpc-starter/docs/server/autoconfiguration#health)
 - gRPC client autoconfiguration
     - [`@Autowired` support](https://danielliu1123.github.io/grpc-starter/docs/client/autoconfiguration#inject-client)
     - [Dynamic refreshing](https://danielliu1123.github.io/grpc-starter/docs/client/dynamic-refresh)
 
-***Extensions:***
+### Extensions:
 
-- [gRPC HTTP transcoding](https://danielliu1123.github.io/grpc-starter/docs/extensions/grpc-http-transcoding): A single codebase to support both gRPC and HTTP/JSON.
-- [Protobuf validation](https://danielliu1123.github.io/grpc-starter/docs/extensions/protobuf-validation): Protobuf message validation implemented by [protovalidate](https://github.com/bufbuild/protovalidate-java)/[protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).
-- [Metrics](https://danielliu1123.github.io/grpc-starter/docs/extensions/metrics): Spring Boot Actuator integration with gRPC service.
-- [Tracing](https://danielliu1123.github.io/grpc-starter/docs/extensions/tracing): Spring Boot Actuator integration with gRPC server and client.
+- [gRPC HTTP transcoding](https://danielliu1123.github.io/grpc-starter/docs/extensions/grpc-http-transcoding): Support both gRPC and HTTP/JSON with a single codebase.
+- [Protobuf validation](https://danielliu1123.github.io/grpc-starter/docs/extensions/protobuf-validation): Protobuf message validation using [protovalidate](https://github.com/bufbuild/protovalidate-java) and [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).
+- [Metrics](https://danielliu1123.github.io/grpc-starter/docs/extensions/metrics): Integrate Spring Boot Actuator with gRPC services.
+- [Tracing](https://danielliu1123.github.io/grpc-starter/docs/extensions/tracing): Integrate Spring Boot Actuator with gRPC server and client.
 - [Testing](https://danielliu1123.github.io/grpc-starter/docs/extensions/test): Integration with `SpringBootTest`.
 
 ## Quick Start
@@ -80,8 +77,7 @@ Please report unacceptable behavior to [email protected].
 
 ## Contributing
 
-The [issue tracker](https://github.com/DanielLiu1123/grpc-starter/issues) is the preferred channel for bug reports,
-feature requests and submitting pull requests.
+Use the [issue tracker](https://github.com/DanielLiu1123/grpc-starter/issues) for bug reports, feature requests, and submitting pull requests.
 
 If you would like to contribute to the project, please refer to [Contributing](./CONTRIBUTING.md).
 

website/docs/01-intro.mdx

@@ -4,41 +4,40 @@ sidebar_position: 1
 
 # Introduction
 
-`grpc-starter` provides a series of Spring Boot starters for the gRPC ecosystem,
-offering autoconfiguration and highly extensible capabilities to enhance the integration between Spring Boot and gRPC.
+`grpc-starter` is a comprehensive suite of Spring Boot starters designed for the gRPC ecosystem. It offers seamless autoconfiguration and highly extensible capabilities to enhance the integration between Spring Boot and gRPC.
 
-## Why Another gRPC Starter
+## Why Choose grpc-starter?
 
-There are already two gRPC Spring Boot starters:
+While there are existing gRPC Spring Boot starters such as:
 
 - [grpc-spring](https://github.com/grpc-ecosystem/grpc-spring)
 - [grpc-spring-boot-starter](https://github.com/LogNet/grpc-spring-boot-starter)
 
-So, why create another one? Here are the main reasons:
+`grpc-starter` was created to address several limitations and provide additional features:
 
-1. The autoconfiguration for gRPC clients is not elegant enough; it does not fully follow the Spring bean lifecycle and requires additional annotations like `@GrpcClient`. We aim to use `@Autowired` directly to inject gRPC clients.
-2. The integration with the surrounding gRPC ecosystem is incomplete, lacking features like gRPC HTTP transcoding, Protobuf validation, test support, etc.
-3. Writing extensions is challenging due to the lack of suitable extension points.
+1. **Elegant Client Autoconfiguration**: Unlike other starters that require additional annotations like `@GrpcClient`, `grpc-starter` allows direct injection of gRPC clients using `@Autowired`, fully adhering to the Spring bean lifecycle.
+2. **Comprehensive Ecosystem Integration**: It includes features like gRPC HTTP transcoding, Protobuf validation, and test support, which are often missing in other starters.
+3. **Ease of Extension**: It provides suitable extension points, making it easier to write and integrate custom extensions.
 
 ## Core Features
 
 ### Client
-  - Autoconfigure gRPC clients: allowing direct injection with `@Autowired` and fully respecting the Spring Bean lifecycle.
-  - Dynamic refreshing: Support to modify gRPC client configurations at runtime without restarting the application.
+- **Autoconfiguration**: Automatically configure gRPC clients, allowing direct injection with `@Autowired` while fully respecting the Spring Bean lifecycle.
+- **Dynamic Refreshing**: Modify gRPC client configurations at runtime without restarting the application.
 
 ### Server
-  - Autoconfigure gRPC servers: write your gRPC service implementation and expose it as a Spring bean, we will take care of the rest.
-  - Exception handling: offering `@ExceptionHandler` like exception handling for gRPC server through `@GrpcAdvice`/`@GrpcExceptionHandler`.
-  - Health check.
+- **Autoconfiguration**: Write your gRPC service implementation and expose it as a Spring bean. The framework handles the rest.
+- **Exception Handling**: Provides `@ExceptionHandler`-like exception handling for gRPC servers through `@GrpcAdvice` and `@GrpcExceptionHandler`.
+- **Health Check**: Built-in health check support for gRPC servers.
 
 ### Extensions
-  - **gRPC HTTP transcoding**: enabling a single codebase to support both gRPC and HTTP/JSON (like [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) but for Java).
-  - **Protobuf validation**: integrating with [protovalidate](https://github.com/bufbuild/protovalidate) and [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).
-  - **Metrics**: supporting metrics through Spring Boot Actuator.
-  - **Tracing**: supporting tracing through Spring Boot Actuator.
-  - **Test**: integrating with `SpringBootTest`.
+- **gRPC HTTP Transcoding**: Enable a single codebase to support both gRPC and HTTP/JSON, similar to [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) but for Java.
+- **Protobuf Validation**: Integrate with [protovalidate](https://github.com/bufbuild/protovalidate) and [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate) for Protobuf message validation.
+- **Metrics**: Support for metrics through Spring Boot Actuator.
+- **Tracing**: Support for tracing through Spring Boot Actuator.
+- **Testing**: Integration with `SpringBootTest` for comprehensive testing support.
 
-This framework is designed for extensibility, and you can easily extend it to suit your needs.
+This framework is designed with extensibility in mind, allowing you to easily extend it to meet your specific needs.
 
 ## Project Structure
 

website/docs/05-quickstart.mdx

@@ -7,12 +7,13 @@ import TabItem from '@theme/TabItem';
 
 # Quick Start
 
-## Dependencies
+## Managing Dependencies
 
-This project offers a BOM (Bill of Materials) to manage the versions of the dependencies.
+To simplify dependency management, this project provides a BOM (Bill of Materials). 
+The BOM ensures that all dependencies are compatible and their versions are managed centrally.
 
 :::info
-All dependencies will assume that `grpc-starter-dependencies` has been used, so all versions will be ignored.
+When using `grpc-starter-dependencies`, you do not need to specify versions for the dependencies listed in the BOM. The BOM will handle the versioning for you.
 :::
 
 <Tabs>
@@ -83,12 +84,12 @@ public class QuickStartApp extends SimpleServiceGrpc.SimpleServiceImplBase {
 }
 ```
 
-No additional annotations or classes are required! Run the application and you will see the `Hello World!`.
+No additional annotations or classes are required! Simply run the application and you will see the `Hello World!` output.
 
-Source code is available at [quick-start](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/quick-start).
+You can find the source code at [quick-start](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/quick-start).
 
 :::tip
-How to setup Protobuf plugin: <br/>
-For Gradle: [multi-module-example](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/multi-module). <br/>
-For Maven: [grpc-starter-maven-demo](https://github.com/DanielLiu1123/grpc-starter-maven-demo).
+Setting up the Protobuf plugin: <br/>
+For Gradle: Refer to the [multi-module-example](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/multi-module). <br/>
+For Maven: Refer to the [grpc-starter-maven-demo](https://github.com/DanielLiu1123/grpc-starter-maven-demo).
 :::

website/docs/10-client/20-dynamic-refresh.mdx

@@ -4,9 +4,10 @@ sidebar_position: 20
 
 # Dynamic Refresh
 
-This feature allows for the dynamic refreshing of gRPC stubs.
-You can place your configuration settings with the `grpc.client` prefix in any configuration center (like [Consul](https://github.com/hashicorp/consul), [Apollo](https://github.com/apolloconfig/apollo), [Nacos](https://github.com/alibaba/nacos), etc.).
-By changing these configurations (e.g. `authority`, `max-inbound-message-size`), gRPC stubs will automatically refresh without the need to restart your application.
+The dynamic refresh feature enables the automatic updating of gRPC stubs without restarting your application. 
+Configuration settings prefixed with `grpc.client` can be placed in any configuration center, 
+such as [Consul](https://github.com/hashicorp/consul), [Apollo](https://github.com/apolloconfig/apollo), or [Nacos](https://github.com/alibaba/nacos). 
+When these configurations (e.g., `authority`, `max-inbound-message-size`) are modified, the gRPC stubs will refresh automatically.
 
 This feature is disabled by default, you can enable it by using the following configuration:
 

website/docs/30-extensions/10-grpc-http-transcoding.mdx

@@ -5,25 +5,25 @@ sidebar_position: 10
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# gRPC HTTP transcoding
+# gRPC HTTP Transcoding
 
-This extension is Java implementation of [gRPC HTTP transcoding](https://cloud.google.com/endpoints/docs/grpc/transcoding),
-like [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) in Go.
+This extension provides a Java implementation of [gRPC HTTP transcoding](https://cloud.google.com/endpoints/docs/grpc/transcoding),
+similar to [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) in Go.
 
-Read [google.api.http](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) specification
-to learn how to define the HTTP mapping.
+Refer to the [google.api.http](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) specification
+to understand how to define HTTP mappings.
 
-## Why Not Sidecar
+## Why Not Use a Sidecar?
 
-Why not just use a sidecar like [Envoy gRPC-JSON transcoder](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter)
-to do the transcoding?
+Why not use a sidecar like [Envoy gRPC-JSON transcoder](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter)
+for transcoding?
 
-- Sidecar is like a black box and is inconvenient for debugging and testing
-- Scalability is not enough, and transcoding customization is challenging.
+- A sidecar acts as a black box, making debugging and testing inconvenient.
+- It lacks sufficient scalability, and customizing transcoding is challenging.
 
 ## Dependencies
 
-Choose the appropriate dependencies based on your stack.
+Select the dependencies that match your technology stack.
 
 <Tabs>
     <TabItem value="webmvc" label="WebMVC">
@@ -97,8 +97,8 @@ Choose the appropriate dependencies based on your stack.
 </Tabs>
 
 :::tip
-Because both webflux and gRPC use netty, if you use the `grpc-netty-shaded` dependency, the final jar package will be larger (~9MB).
-Therefore, exclude the `grpc-netty-shaded` dependency and use the `grpc-netty` dependency instead.
+Since both WebFlux and gRPC utilize Netty, using the `grpc-netty-shaded` dependency will increase the size of the final JAR package by approximately 9MB. 
+To avoid this, exclude the `grpc-netty-shaded` dependency and use the `grpc-netty` dependency instead.
 :::
 
 ## Example
@@ -316,12 +316,10 @@ it will automatically find the gRPC server endpoint of the current application.
 
 ## How It Works
 
-1. When the application starts up,
-it will get all the protobuf configurations for HTTP mapping (google.api.http),
-and then register them into the internally implemented [`RouterFunction`](https://docs.spring.io/spring-framework/reference/web/webmvc-functional.html#webmvc-fn-overview).
+1. During application startup, all protobuf configurations for HTTP mapping (google.api.http) are retrieved 
+and registered into the internally implemented [`RouterFunction`](https://docs.spring.io/spring-framework/reference/web/webmvc-functional.html#webmvc-fn-overview).
 
-2. When an HTTP request comes in, the `RouterFunction` will find the corresponding gRPC service based on the request’s URL and method,
-then convert the HTTP request into a gRPC request,
-send it to the gRPC server endpoint, and finally convert the gRPC response back into an HTTP response to return.
+2. When an HTTP request is received, the `RouterFunction` identifies the corresponding gRPC service based on the request’s URL and method. 
+It then converts the HTTP request into a gRPC request, sends it to the gRPC server endpoint, and finally converts the gRPC response back into an HTTP response to return to the client.
 
-Refer to [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway?tab=readme-ov-file#about) for more details.
+For more details, refer to [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway?tab=readme-ov-file#about).

website/docs/30-extensions/20-protobuf-validation.mdx

@@ -7,8 +7,8 @@ import TabItem from '@theme/TabItem';
 
 # Protobuf Validation
 
-This extension integrates [protovalidate](https://github.com/bufbuild/protovalidate-java) and [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).
-They are used to validate the Protobuf messages.
+This extension integrates two powerful tools for validating Protobuf messages: [protovalidate](https://github.com/bufbuild/protovalidate-java) and [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate).
+These tools ensure that your Protobuf messages adhere to the defined validation rules.
 
 :::tip
 `protovalidate` is the successor to `protoc-gen-validate`, so it is recommended to use `protovalidate`.

website/docs/40-configuration-properties.md

@@ -318,4 +318,4 @@ This page was generated by [spring-configuration-property-documenter](https://gi
 | enabled| java.lang.Boolean| Whether to enable validation, default is \{@code true}.| true| | 
 | order| java.lang.Integer| Validating interceptor order, default is \{@code 0}.| 0| | 
 
-This is a generated file, generated at: **2024-09-24T22:09:25.311747**
+This is a generated file, generated at: **2024-09-24T23:08:36.582836**

website/docs/50-version.mdx

@@ -4,9 +4,8 @@ sidebar_position: 50
 
 # Version
 
-[`grpc-starter-dependencies`](https://central.sonatype.com/artifact/io.github.danielliu1123/grpc-starter-dependencies)
-provides dependency management for gRPC and Protobuf, so you only need to use the version
-of `grpc-starter-dependencies` aligned with Spring Boot.
+The `grpc-starter-dependencies` project simplifies dependency management for gRPC and Protobuf by aligning its versions with Spring Boot. 
+This ensures compatibility and reduces the need for manual version management.
 
 | Spring Boot    | grpc-starter-dependencies | grpc-java | protobuf-java |
 |----------------|---------------------------|-----------|---------------|
@@ -15,25 +14,24 @@ of `grpc-starter-dependencies` aligned with Spring Boot.
 | 3.1.x          | 3.1.8                     | 1.59.1    | 3.25.1        |      
 | 2.x (>= 2.4.0) | 2.1.6                     | 1.59.1    | 3.25.1        |
 
-If you want to find the versions of `grpc-java` and `protobuf-java` used by `grpc-starter-dependencies`,
-you can check [grpc-starter-dependencies](https://central.sonatype.com/artifact/io.github.danielliu1123/grpc-starter-dependencies).
+To find the specific versions of `grpc-java` and `protobuf-java` used by `grpc-starter-dependencies`, 
+visit the [grpc-starter-dependencies](https://central.sonatype.com/artifact/io.github.danielliu1123/grpc-starter-dependencies) page.
 
 :::tip
-The version of `grpc-starter-dependencies` is aligned with Spring Boot,
-we check the latest version of Spring Boot daily and release the corresponding version.
+The `grpc-starter-dependencies` version is kept in sync with the latest Spring Boot releases. 
+We monitor Spring Boot updates daily and release corresponding versions to ensure compatibility.
 :::
 
-## Release Notes to be Noticed
+## Important Release Notes
 
-- [3.3.1](https://github.com/DanielLiu1123/grpc-starter/releases/tag/v3.3.1)
+### Version 3.3.1
 
-  - Removed `javax.annotation:javax.annotation-api` dependency.
+- **Dependency Removal**: The `javax.annotation:javax.annotation-api` dependency has been removed.
+- **Configuration Guide**: Instructions on configuring gRPC to avoid generating the `javax.annotation.Generated` annotation:
+  - [Maven Configuration](https://github.com/DanielLiu1123/grpc-starter-maven-demo/blob/main/pom.xml#L92)
+  - [Gradle Configuration](https://github.com/DanielLiu1123/grpc-starter/blob/main/gradle/protobuf.gradle#L15)
+  - [Buf Configuration](https://github.com/DanielLiu1123/grpc-starter/blob/main/examples/transcoding/best-practice/bp-api/buf.gen.yaml#L7)
 
-  - How to configure gRPC to not generate `javax.annotation.Generated` annotation:
-    - [Maven](https://github.com/DanielLiu1123/grpc-starter-maven-demo/blob/main/pom.xml#L92)
-    - [Gradle](https://github.com/DanielLiu1123/grpc-starter/blob/main/gradle/protobuf.gradle#L15)
-    - [Buf](https://github.com/DanielLiu1123/grpc-starter/blob/main/examples/transcoding/best-practice/bp-api/buf.gen.yaml#L7)
+### Version 3.2.0
 
-- 3.2.0
-
-  - The groupId has been changed to `io.github.danielliu1123` from `com.freemanan`.
+- **Group ID Change**: The groupId has been updated from `com.freemanan` to `io.github.danielliu1123`.