refactor!: Rename Builder.addHandler to extraRoute

Reads more honestly. "handlers" and "addHandler" sounded like the same
concept but they aren't — handlers(Map) is operationId-keyed and validated
against the OpenAPI spec; the other is path-keyed and bypasses validation.
"extraRoute" makes that distinction visible at the call site:

    .handlers(handlerMap)                         // OpenAPI operations
    .extraRoute("/alive", Handlers.aliveHandler())  // side route

Author: thced

README.md

@@ -364,8 +364,8 @@ to OpenAPI parameter / body validation.
 var server = OpenApiServer.builder()
     .spec(spec)
     .handlers(handlers)
-    .addHandler("/alive", Handlers.aliveHandler())
-    .addHandler("/schemas/v1/openapi.yaml",
+    .extraRoute("/alive", Handlers.aliveHandler())
+    .extraRoute("/schemas/v1/openapi.yaml",
                 Handlers.specHandler("/schemas/v1/openapi.yaml"))
     .build();
 ```

src/main/java/com/retailsvc/http/OpenApiServer.java

@@ -197,11 +197,17 @@ public Builder shutdownTimeoutSeconds(int shutdownTimeoutSeconds) {
       return this;
     }
 
-    public Builder addHandler(String path, HttpHandler handler) {
+    /**
+     * Registers an extra HTTP route at {@code path} that bypasses OpenAPI validation and routing.
+     * Use for side concerns like {@code /alive}, {@code /health}, or serving the spec itself —
+     * anything that isn't an OpenAPI {@code operationId}. For OpenAPI-described operations use
+     * {@link #handlers(Map)}.
+     */
+    public Builder extraRoute(String path, HttpHandler handler) {
       requireNonNull(path, "path must not be null");
       requireNonNull(handler, "handler must not be null");
       if (extras.containsKey(path)) {
-        throw new IllegalStateException("duplicate extra handler path: " + path);
+        throw new IllegalStateException("duplicate extra route path: " + path);
       }
       extras.put(path, handler);
       return this;

src/test/java/com/retailsvc/http/ExtraHandlersIT.java

@@ -19,7 +19,7 @@ void aliveExtraReturns204AndBypassesValidation() throws Exception {
                 .handlers(Map.of())
                 .exceptionHandler(defaultExceptionHandler())
                 .port(0)
-                .addHandler("/alive", Handlers.aliveHandler())
+                .extraRoute("/alive", Handlers.aliveHandler())
                 .build();
         var client = httpClient()) {
 
@@ -43,7 +43,7 @@ void specHandlerServesClasspathResource() throws Exception {
                 .handlers(Map.of())
                 .exceptionHandler(defaultExceptionHandler())
                 .port(0)
-                .addHandler("/openapi.yaml", Handlers.specHandler("/openapi.yaml"))
+                .extraRoute("/openapi.yaml", Handlers.specHandler("/openapi.yaml"))
                 .build();
         var client = httpClient()) {
 
@@ -73,7 +73,7 @@ void extraHandlerExceptionFlowsThroughExceptionHandler() throws Exception {
                 .handlers(Map.of())
                 .exceptionHandler(defaultExceptionHandler())
                 .port(0)
-                .addHandler("/boom", boom)
+                .extraRoute("/boom", boom)
                 .build();
         var client = httpClient()) {
 

src/test/java/com/retailsvc/http/OpenApiServerBuilderTest.java

@@ -28,9 +28,9 @@ void buildsWithRequiredFieldsOnly() {
   void rejectsDuplicateExtraPathOnSecondAddHandler() {
     HttpHandler duplicate = Handlers.aliveHandler();
     OpenApiServer.Builder b =
-        OpenApiServer.builder().spec(spec).handlers(emptyMap()).addHandler("/alive", duplicate);
+        OpenApiServer.builder().spec(spec).handlers(emptyMap()).extraRoute("/alive", duplicate);
 
-    assertThatThrownBy(() -> b.addHandler("/alive", duplicate))
+    assertThatThrownBy(() -> b.extraRoute("/alive", duplicate))
         .isInstanceOf(IllegalStateException.class)
         .hasMessageContaining("/alive");
   }
@@ -42,7 +42,7 @@ void rejectsExtraPathEqualToSpecBasePathAtBuildTime() {
         OpenApiServer.builder()
             .spec(spec)
             .handlers(emptyMap())
-            .addHandler("/api", Handlers.aliveHandler())
+            .extraRoute("/api", Handlers.aliveHandler())
             .port(0);
 
     assertThatThrownBy(b::build)