This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new b10f07721 More docs.
b10f07721 is described below
commit b10f07721c4923faea225914af0ba2b66842fa85
Author: James Bognar <[email protected]>
AuthorDate: Sun Sep 28 12:14:04 2025 -0400
More docs.
---
README.md | 1 +
.../topics/01.01.00.JuneauEcosystemOverview.md | 2 +-
juneau-docs/docs/topics/01.11.00.WhyJuneau.md | 259 +++++++++++++++++++++
juneau-docs/sidebars.ts | 5 +
4 files changed, 266 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index e0ed8e38f..09ebc9287 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@
### Documentation
* **[Javadocs](https://juneau.staged.apache.org/site/apidocs/)** - Complete
API documentation
* **[User
Guide](https://juneau.staged.apache.org/docs/topics/JuneauEcosystemOverview)**
- Comprehensive framework documentation
+* **[Why Choose
Juneau?](https://juneau.staged.apache.org/docs/topics/WhyJuneau)** - Benefits
and comparisons with alternatives
* **[Framework
Comparisons](https://juneau.staged.apache.org/docs/topics/FrameworkComparisons)**
- Compare Juneau with Jackson, Spring Boot, and JAX-RS
*
**[Examples](https://juneau.staged.apache.org/docs/topics/JuneauExamplesCore)**
- Code examples and tutorials
*
[juneau-examples-core](https://juneau.staged.apache.org/docs/topics/JuneauExamplesCore)
- Core serialization examples
diff --git a/juneau-docs/docs/topics/01.01.00.JuneauEcosystemOverview.md
b/juneau-docs/docs/topics/01.01.00.JuneauEcosystemOverview.md
index 24fbdc9bc..3d3125df3 100644
--- a/juneau-docs/docs/topics/01.01.00.JuneauEcosystemOverview.md
+++ b/juneau-docs/docs/topics/01.01.00.JuneauEcosystemOverview.md
@@ -24,7 +24,7 @@ Juneau excels in the following scenarios:
#### When to Choose Juneau
-Not sure if Juneau is right for your project? Check out our detailed
[Framework Comparisons](/docs/topics/FrameworkComparisons) page to see how
Juneau compares to Jackson, Spring Boot, and JAX-RS.
+Not sure if Juneau is right for your project? Check out our detailed [Why
Choose Juneau?](/docs/topics/WhyJuneau) page for a comprehensive comparison
with alternatives, or see our [Framework
Comparisons](/docs/topics/FrameworkComparisons) page for detailed technical
comparisons.
**Quick summary:** Choose Juneau when you need multi-format serialization,
REST APIs with automatic content negotiation, or want an integrated solution
with minimal dependencies.
diff --git a/juneau-docs/docs/topics/01.11.00.WhyJuneau.md
b/juneau-docs/docs/topics/01.11.00.WhyJuneau.md
new file mode 100644
index 000000000..a0fea915c
--- /dev/null
+++ b/juneau-docs/docs/topics/01.11.00.WhyJuneau.md
@@ -0,0 +1,259 @@
+---
+title: "Why Choose Juneau?"
+slug: WhyJuneau
+---
+
+# Why Choose Juneau?
+
+Apache Juneau™ offers a unique combination of simplicity, power, and
zero-dependency design that makes it an excellent choice for modern Java
development. Here's why developers choose Juneau over alternatives.
+
+## The Juneau Advantage
+
+### **Zero Dependencies, Maximum Power**
+
+Unlike other frameworks that require multiple dependencies and complex
configurations, Juneau provides comprehensive functionality with minimal
external requirements:
+
+**Juneau:**
+```xml
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-all</artifactId>
+ <version>9.1.0</version>
+</dependency>
+```
+
+**Alternative (Spring Boot + Jackson + Swagger):**
+```xml
+<dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-web</artifactId>
+</dependency>
+<dependency>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.springfox</groupId>
+ <artifactId>springfox-swagger2</artifactId>
+</dependency>
+<!-- Plus many more dependencies -->
+```
+
+### **Unified API, Multiple Formats**
+
+Juneau provides a single, consistent API for serializing to multiple formats:
+
+```java
+// One API, multiple formats
+Person person = new Person("John", 30);
+
+// JSON
+String json = JsonSerializer.DEFAULT.serialize(person);
+
+// XML
+String xml = XmlSerializer.DEFAULT.serialize(person);
+
+// HTML
+String html = HtmlSerializer.DEFAULT.serialize(person);
+
+// URL-Encoding
+String urlEnc = UrlEncodingSerializer.DEFAULT.serialize(person);
+```
+
+**With alternatives, you need different libraries and APIs for each format.**
+
+### **Self-Documenting REST APIs**
+
+Juneau automatically generates Swagger documentation from your POJOs and
annotations:
+
+```java
+@Rest(title="User API", description="User management service")
+public class UserResource extends BasicRestServlet {
+
+ @RestGet("/users/{id}")
+ public User getUser(@Path String id) {
+ return userService.findById(id);
+ }
+
+ @RestPost("/users")
+ public User createUser(@Body User user) {
+ return userService.create(user);
+ }
+}
+```
+
+**Result:** Automatic Swagger UI at `/swagger-ui.html` with full API
documentation, request/response schemas, and interactive testing.
+
+### **Type-Safe REST Client Proxies**
+
+Create type-safe client interfaces that feel like local method calls:
+
+```java
+@Remote("http://api.example.com";)
+public interface UserService {
+ @Get("/users/{id}")
+ User getUser(@Path String id);
+
+ @Post("/users")
+ User createUser(@Body User user);
+}
+
+// Use like a regular Java interface
+UserService service = RestClient.create().build().getRemote(UserService.class);
+User user = service.getUser("123");
+```
+
+**No more manual HTTP client code, JSON parsing, or error handling.**
+
+### **Serverless Testing**
+
+Test REST APIs without starting servers or containers:
+
+```java
+@Test
+public void testUserAPI() throws Exception {
+ String response = MockRestClient
+ .create(UserResource.class)
+ .json5()
+ .build()
+ .get("/users/123")
+ .run()
+ .assertStatus().is(200)
+ .getContent().asString();
+
+ assertThat(response).contains("John");
+}
+```
+
+**Fast, reliable tests that don't require external dependencies.**
+
+## Comparison with Popular Alternatives
+
+### vs. Jackson
+
+| Feature | Juneau | Jackson |
+|---------|--------|---------|
+| **Formats Supported** | JSON, XML, HTML, URL-Encoding, UON, OpenAPI,
PlainText, CSV, SOAP, MessagePack, RDF | JSON only |
+| **REST API Support** | Built-in with automatic Swagger | Requires additional
frameworks |
+| **Configuration** | Zero configuration | Requires setup and configuration |
+| **Testing Support** | Built-in MockRestClient | Requires external testing
tools |
+| **Dependencies** | Self-contained | Requires additional libraries for other
formats |
+
+**Juneau Advantage:** Single library for multiple formats + REST APIs +
testing, while Jackson only handles JSON serialization.
+
+### vs. Spring Boot Web Controllers
+
+| Feature | Juneau | Spring Boot |
+|---------|--------|-------------|
+| **Content Negotiation** | Automatic for all formats | Manual setup required |
+| **API Documentation** | Automatic Swagger generation | Requires additional
configuration |
+| **Testing** | Built-in MockRestClient | Requires @WebMvcTest or
TestContainers |
+| **Dependencies** | Minimal | Heavy framework with many dependencies |
+| **Learning Curve** | Simple POJO-based approach | Complex annotation system |
+
+**Juneau Advantage:** Simpler, more focused approach with built-in features
that require additional setup in Spring Boot.
+
+### vs. JAX-RS
+
+| Feature | Juneau | JAX-RS |
+|---------|--------|--------|
+| **Implementation** | Single implementation | Multiple competing
implementations |
+| **Content Negotiation** | Automatic | Manual configuration |
+| **Documentation** | Automatic Swagger | Requires additional tools |
+| **Testing** | Built-in support | Requires external testing frameworks |
+| **Dependencies** | Self-contained | Requires implementation + additional
libraries |
+
+**Juneau Advantage:** Complete solution vs. specification that requires
multiple libraries and configuration.
+
+## Real-World Benefits
+
+### **Enterprise Development**
+
+- **Reduced Complexity:** Fewer dependencies mean fewer security
vulnerabilities and maintenance overhead
+- **Faster Onboarding:** New developers can be productive immediately with
intuitive POJO-based APIs
+- **Consistent APIs:** Same patterns across serialization, REST services, and
testing
+- **Built-in Documentation:** Automatic Swagger generation reduces
documentation maintenance
+
+### **Microservices**
+
+- **Lightweight:** Minimal memory footprint and fast startup times
+- **Self-Contained:** No external dependencies to manage in containers
+- **Flexible Deployment:** Works with any Servlet 3.1+ container or embedded
Jetty
+- **Easy Testing:** MockRestClient enables comprehensive testing without
external services
+
+### **API Development**
+
+- **Rapid Prototyping:** Create working APIs in minutes, not hours
+- **Automatic Documentation:** Swagger UI generated automatically from your
code
+- **Content Negotiation:** Support multiple formats with zero additional
configuration
+- **Type Safety:** Compile-time checking for REST client interfaces
+
+## When to Choose Juneau
+
+### **Perfect For:**
+
+- **Multi-format APIs:** When you need to support JSON, XML, HTML, and other
formats
+- **Rapid Development:** When you want to build APIs quickly without complex
configuration
+- **Microservices:** When you need lightweight, self-contained services
+- **Testing:** When you want comprehensive testing without external
dependencies
+- **Documentation:** When you need automatic API documentation generation
+- **Learning:** When you want to understand REST APIs without framework
complexity
+
+### **Consider Alternatives If:**
+
+- **Heavy Spring Ecosystem:** You're already deeply invested in Spring Boot's
ecosystem
+- **Complex Enterprise Features:** You need advanced enterprise features like
distributed transactions
+- **Large Team:** Your team has extensive experience with other frameworks
+- **Legacy Integration:** You need to integrate with existing Spring-based
systems
+
+## Getting Started
+
+Ready to try Juneau? Here's how to get started:
+
+### 1. Add Dependency
+
+```xml
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-all</artifactId>
+ <version>9.1.0</version>
+</dependency>
+```
+
+### 2. Create Your First API
+
+```java
+@Rest(title="My API")
+public class HelloResource extends BasicRestServlet {
+
+ @RestGet("/hello/{name}")
+ public String sayHello(@Path String name) {
+ return "Hello " + name + "!";
+ }
+}
+```
+
+### 3. Deploy and Test
+
+```java
+// Deploy to any Servlet container or use embedded Jetty
+// Automatic Swagger UI available at /swagger-ui.html
+// Test with MockRestClient
+```
+
+## Community and Support
+
+- **Documentation:** Comprehensive guides and examples at
[juneau.staged.apache.org](https://juneau.staged.apache.org/)
+- **Examples:** Working code examples in the
[juneau-examples](https://github.com/apache/juneau-examples) repository
+- **Community:** Join discussions on the [Apache Juneau mailing
list](mailto:[email protected])
+- **Issues:** Report bugs and request features on [GitHub
Issues](https://github.com/apache/juneau/issues)
+
+## Conclusion
+
+Juneau offers a compelling alternative to complex, multi-library solutions. By
providing a unified API for serialization, REST services, and testing with
minimal dependencies, Juneau enables developers to focus on business logic
rather than framework configuration.
+
+**Try Juneau today and experience the simplicity of zero-dependency Java
development.**
+
+---
+
+*Still not convinced? Check out our [Framework
Comparisons](/docs/topics/FrameworkComparisons) page for detailed technical
comparisons, or explore our [comprehensive
examples](/docs/topics/JuneauExamplesCore) to see Juneau in action.*
diff --git a/juneau-docs/sidebars.ts b/juneau-docs/sidebars.ts
index 974887619..1caee736c 100644
--- a/juneau-docs/sidebars.ts
+++ b/juneau-docs/sidebars.ts
@@ -89,6 +89,11 @@ const sidebars: SidebarsConfig = {
id: 'topics/01.10.00.FrameworkComparisons',
label: '1.10. Framework Comparisons',
},
+ {
+ type: 'doc',
+ id: 'topics/01.11.00.WhyJuneau',
+ label: '1.11. Why Choose Juneau?',
+ },
],
},
{
