Merge branch 'main' into grpc

Author: jknack

README.md

@@ -7,8 +7,24 @@
 
 # ∞ do more, more easily
 
-[Jooby](https://jooby.io) is a modern, performant and easy to use web framework for Java and Kotlin built on top of your
-favorite web server.
+[Jooby](https://jooby.io) is a modern, high-performance web framework for Java and Kotlin, designed to run seamlessly atop your preferred web server.
+
+## 🚀 Built for Speed
+- **High Performance**: Consistently ranks among the fastest Java frameworks in TechEmpower benchmarks.
+- **Lightweight Footprint**: Low memory usage and fast startup times make it ideal for microservices environments.
+- **Choose Your Engine**: Built to run on your favorite high-performance servers: Netty, Jetty, or Undertow.
+
+## 🛠️ Developer Productivity
+- **Instant Hot-Reload**: Save your code and see changes immediately without restarting the entire JVM.
+- **Modular by Design**: Only use what you need. Jooby offers over 50 "thin" modules for database access (Hibernate, JDBI, Flyway), security (Pac4j), and more.
+- **OpenAPI & Swagger**: Automatically generate interactive documentation for your APIs with built-in OpenAPI 3 support.
+
+## 🧩 Unrivaled Flexibility
+- **The Power of Choice**: Use the Script API (fluent, lambda-based routes) for simple apps, or the MVC API (annotation-based) for complex enterprise projects.
+- **Reactive & Non-Blocking**: Full support for modern async patterns, including Kotlin Coroutines, RxJava, Reactor, and CompletableFutures.
+- **First-Class Kotlin Support**: Native DSLs and features designed specifically to make Kotlin development feel intuitive and type-safe.
+
+## Quick Start
 
 Java:
 
@@ -72,11 +88,6 @@ Previous version
 - v2: [Documentation](https://jooby.io/v2) and [source code](https://github.com/jooby-project/jooby/tree/2.x)
 - v1: [Documentation](https://jooby.io/v1) and [source code](https://github.com/jooby-project/jooby/tree/1.x)
 
-author
-=====
-
- [Edgar Espina](https://twitter.com/edgarespina)
-
 license
 =====
 

docs/asciidoc/migration/4.x.adoc

@@ -10,6 +10,23 @@ This is a **work in progress** document, if something is wrong or missing please
 
 - Java 21 as minimum
 
+==== Special HTTP names
+
+Starting from 4.0.7 `@XXXParam` the default annotation `value` attribute is actually that: *the default value*
+of the parameter. In previous version this was used it for `invalid/special HTTP names`.
+
+In 3.x:
+
+    @QuerParam("some-http-name") String name
+
+In 4.x
+
+    @QuerParam(name = "some-http-name") String name
+
+The `value` is now reserved for default values:
+
+    @QueryParam("20") int pageSize
+
 ==== Buffer API
 
 The package `io.jooby.buffer` is gone. It was replaced by `io.jooby.output` these classes

docs/asciidoc/modules/openapi-ascii.adoc

@@ -4,7 +4,7 @@
 
 1) create your template: `doc/library.adoc`
 
-[source, asciidoc]
+[source, twig]
 ----
 = 📚 {{info.title}} Guide
 :source-highlighter: highlightjs
@@ -250,7 +250,7 @@ Only for Schemas.
 ====== A. Documenting a Route (The "Standard" Block)
 Use this pattern to document a specific endpoint, separating path parameters from query parameters.
 
-[source, asciidoc]
+[source, twig]
 ----
 // 1. Define the route
 {% set route = GET("/library/books/{isbn}") %}

docs/asciidoc/modules/openapi.adoc

@@ -11,7 +11,7 @@ This library supports:
 - https://github.com/Redocly/redoc[Redoc] (Optional)
 - AsciiDoc Output (Optional)
 
-Checkout the [demo project](https://github.com/jooby-project/library-demo)
+Checkout the https://github.com/jooby-project/library-demo[demo project]
 
 === Configuration
 
@@ -34,10 +34,7 @@ Checkout the [demo project](https://github.com/jooby-project/library-demo)
           <goal>openapi</goal>
         </goals>
         <configuration>
-          <specVersion>...</specVersion>
-          <adoc>
-            <file>...</file>
-          </adoc>
+          ...
         </configuration>
       </execution>
     </executions>
@@ -66,6 +63,12 @@ plugins {
 mainClassName = "myapp.App"
 ...
 
+// Configuration
+
+openAPI {
+  ....
+}
+
 // Run openAPI task on joobyRun
 joobyRun.dependsOn openAPI
 
@@ -80,6 +83,53 @@ It may slow down `hot reload` process in case of large projects with a lot of co
 To avoid this behaviour you can specify maven build phase which suits your needs better (e.g. `prepare-package`).
 ====
 
+==== Options
+
+[cols="1,1,4a"]
+|===
+| Option | Default Value | Description
+
+|`adoc`
+| 
+|List of asciidoc files used as template to generate documentation:
+
+.Maven:
+
+    <adoc>
+      <file>guide.adoc</file>
+     </adoc>
+
+.Gradle:
+    {
+      adoc = ["guide.adoc"]
+    }
+
+|`basedir`
+| `${project.dir}`
+|Set base directory used it for loading openAPI template file name.
+
+|`excludes`
+|
+|Regular expression used to excludes route. Example: `/web`.
+
+|`includes`
+| 
+|Regular expression used to includes/keep route. Example: `/api/.*`.
+
+|`javadoc`
+|`on/true`
+|Turn on/off javadoc generation from Java source files. Set to `off` or `false` to turn it off.
+
+|`specVersion`
+|`3.0`
+|Set the desired spec output. Possible values: `3.0` or `3.1`
+
+|`templateName`
+|`openapi.yaml`
+|Set openAPI template file path.
+
+|===
+
 === Usage
 
 To learn how it works, let's write a simple Pet API:
@@ -145,7 +195,7 @@ You will find the files in the output build directory. If your application is `b
 This is the main difference with previous version. We moved from runtime to build time generation. This way we:
 
 - Are able to get our OpenAPI files at build time (of course)
-- At runtime we don't waste resources (CPU, memory) while analyze and build the OpenAPI model
+- At runtime, we don't waste resources (CPU, memory) while analyze and build the OpenAPI model
 - We keep bootstrap as fast as possible
 ====
 
@@ -204,11 +254,11 @@ properties filter routes by their path pattern. The filter is a regular expressi
 
 === Documenting your API
 
-Full/complete example available [here](https://github.com/jooby-project/library-demo)
+Full/complete example available https://github.com/jooby-project/library-demo[here]
 
 ==== JavaDoc comments
 
-JavaDoc comments are supported on Java in script and MVC routes.
+JavaDoc comments are supported for script and MVC routes on Java code base. They are enable by default, to turn them off set `javadoc: off` or `javadoc: false` in your maven/gradle plugin.
 
 .Script routes
 [source,java, role="primary"]

docs/js/highlight.min.js

@@ -46,7 +46,7 @@ public static void generate(Path basedir, boolean publish, boolean v1, boolean d
     String version = version();
     // 2.x/3.x/main
     var branch = new Git("jooby-project", "jooby", Paths.get(System.getProperty("user.dir"))).currentBranch();
-    var uiVersion = branch.equals("main") ? "" : "/v" + branch.replace(".x", "");
+    var uiVersion = branch.endsWith(".x") ? "/v" + branch.replace(".x", "") : "";
 
     Path asciidoc = basedir.resolve("asciidoc");
 
@@ -267,7 +267,7 @@ private static Options createOptions(Path basedir, Path outdir, String version,
     attributes.imagesDir("images");
     attributes.sourceHighlighter("highlightjs");
     attributes.attribute("highlightjsdir", "js");
-    // agate, tom-one-dark, tomorrow-night-bright, tokyo-night-dark
+    // agate, atom-one-dark, tomorrow-night-bright, tokyo-night-dark
     attributes.attribute("highlightjs-theme", "agate");
     attributes.attribute("favicon", "images/favicon96.png");
 

docs/js/styles/tokyo-night-dark.min.css

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.jooby</groupId>
     <artifactId>jooby-project</artifactId>
-    <version>4.0.14-SNAPSHOT</version>
+    <version>4.0.16-SNAPSHOT</version>
   </parent>
   <artifactId>jooby</artifactId>
   <name>jooby</name>

docs/js/styles/tomorrow-night-bright.min.css

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.jooby</groupId>
     <artifactId>modules</artifactId>
-    <version>4.0.14-SNAPSHOT</version>
+    <version>4.0.16-SNAPSHOT</version>
   </parent>
   <artifactId>jooby-apt</artifactId>
   <name>jooby-apt</name>