- add path filter with replace query and path paramters

- better format for table output (long description column)
- ref #3820

Author: jknack

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/OpenAPIExt.java

@@ -243,7 +243,7 @@ public OperationExt findOperationById(String operationId) {
   }
 
   public OperationExt findOperation(String method, String pattern) {
-    Predicate<OperationExt> filter = op -> op.getPattern().equals(pattern);
+    Predicate<OperationExt> filter = op -> op.getPath().equals(pattern);
     if (method != null) {
       filter = filter.and(op -> op.getMethod().equals(method));
     }

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/OperationExt.java

@@ -27,7 +27,7 @@ public class OperationExt extends io.swagger.v3.oas.models.Operation {
 
   @JsonIgnore private final MethodNode node;
   @JsonIgnore private String method;
-  @JsonIgnore private final String pattern;
+  @JsonIgnore private final String path;
   @JsonIgnore private Boolean hidden;
   @JsonIgnore private LinkedList<String> produces = new LinkedList<>();
   @JsonIgnore private LinkedList<String> consumes = new LinkedList<>();
@@ -41,10 +41,10 @@ public class OperationExt extends io.swagger.v3.oas.models.Operation {
   @JsonIgnore private ClassNode controller;
 
   public OperationExt(
-      MethodNode node, String method, String pattern, List arguments, ResponseExt response) {
+      MethodNode node, String method, String path, List arguments, ResponseExt response) {
     this.node = node;
     this.method = method.toUpperCase();
-    this.pattern = pattern;
+    this.path = path;
     setParameters(arguments);
     this.defaultResponse = response;
     setResponses(apiResponses(Collections.singletonList(response)));
@@ -87,8 +87,8 @@ public void setMethod(String method) {
     this.method = method;
   }
 
-  public String getPattern() {
-    return pattern;
+  public String getPath() {
+    return path;
   }
 
   public List<String> getProduces() {
@@ -120,7 +120,7 @@ public void setHidden(Boolean hidden) {
   }
 
   public String toString() {
-    return getMethod() + " " + getPattern();
+    return getMethod() + " " + getPath();
   }
 
   public Parameter getParameter(int i) {
@@ -267,4 +267,8 @@ public OperationExt copy(String pattern) {
     copy.setPathExtensions(getPathExtensions());
     return copy;
   }
+
+  public String getPath(Map<String, Object> pathParams) {
+    return Router.reverse(getPath(), pathParams);
+  }
 }

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java

@@ -75,7 +75,7 @@ public List<OperationExt> parse(ParserContext ctx, OpenAPIExt openapi) {
 
     List<OperationExt> result = new ArrayList<>();
     for (OperationExt operation : operations) {
-      List<String> patterns = Router.expandOptionalVariables(operation.getPattern());
+      List<String> patterns = Router.expandOptionalVariables(operation.getPath());
       if (patterns.size() == 1) {
         result.add(operation);
       } else {
@@ -112,8 +112,7 @@ private static void addJavaDoc(
       if (operation.getController() == null) {
         javaDoc
             .flatMap(
-                doc ->
-                    doc.getScript(operation.getMethod(), operation.getPattern().substring(offset)))
+                doc -> doc.getScript(operation.getMethod(), operation.getPath().substring(offset)))
             .ifPresent(
                 scriptDoc -> {
                   if (scriptDoc.getPath() != null) {
@@ -249,8 +248,7 @@ private void uniqueOperationId(List<OperationExt> operations) {
   private String operationId(OperationExt operation) {
     return Optional.ofNullable(operation.getOperationId())
         .orElseGet(
-            () ->
-                operation.getMethod().toLowerCase() + patternToOperationId(operation.getPattern()));
+            () -> operation.getMethod().toLowerCase() + patternToOperationId(operation.getPath()));
   }
 
   private String patternToOperationId(String pattern) {

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/asciidoc/Functions.java

@@ -24,7 +24,7 @@ public List<String> getArgumentNames() {
     @Override
     public Object execute(
         Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
-      args.put("method", name());
+      args.put("identifier", name());
       return operation.execute(args, self, context, lineNumber);
     }
   },
@@ -37,7 +37,7 @@ public List<String> getArgumentNames() {
     @Override
     public Object execute(
         Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
-      args.put("method", name());
+      args.put("identifier", name());
       return operation.execute(args, self, context, lineNumber);
     }
   },
@@ -50,7 +50,7 @@ public List<String> getArgumentNames() {
     @Override
     public Object execute(
         Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
-      args.put("method", name());
+      args.put("identifier", name());
       return operation.execute(args, self, context, lineNumber);
     }
   },
@@ -63,7 +63,7 @@ public List<String> getArgumentNames() {
     @Override
     public Object execute(
         Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
-      args.put("method", name());
+      args.put("identifier", name());
       return operation.execute(args, self, context, lineNumber);
     }
   },
@@ -76,7 +76,7 @@ public List<String> getArgumentNames() {
     @Override
     public Object execute(
         Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
-      args.put("method", name());
+      args.put("identifier", name());
       return operation.execute(args, self, context, lineNumber);
     }
   },

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/asciidoc/OperationFilters.java

@@ -15,6 +15,7 @@
 import com.google.common.base.Predicate;
 import com.google.common.base.Splitter;
 import com.google.common.collect.*;
+import com.google.common.net.UrlEscapers;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 import io.jooby.MediaType;
@@ -46,13 +47,8 @@ protected String doApply(
         int lineNumber)
         throws Exception {
       var options = args(args);
-      var method =
-          Optional.of(options.removeAll("-X"))
-              .map(Collection::iterator)
-              .filter(Iterator::hasNext)
-              .map(Iterator::next)
-              .orElse(operation.getMethod())
-              .toUpperCase();
+      var method = removeOption(options, "-X", operation.getMethod()).toUpperCase();
+      var language = removeOption(options, "language", "");
       /* Accept/Content-Type: */
       var addAccept = true;
       var addContentType = true;
@@ -111,11 +107,21 @@ protected String doApply(
                 .collect(Collectors.joining("&", "?", ""));
       }
       options.put("-X", method + " '" + url + "'");
-      var optionString = toString(options);
-      snippetContext.put("options", optionString);
+      var optionsString = toString(options);
+      snippetContext.put("options", optionsString);
+      snippetContext.put("language", language);
       return resolver.apply(id(), snippetContext);
     }
 
+    @NonNull private static String removeOption(
+        Multimap<String, String> options, String name, String defaultValue) {
+      return Optional.of(options.removeAll(name))
+          .map(Collection::iterator)
+          .filter(Iterator::hasNext)
+          .map(Iterator::next)
+          .orElse(defaultValue);
+    }
+
     @NonNull private static Stream<Map.Entry<String, String>> encodeUrlParameter(List<Parameter> query) {
       return query.stream()
           .flatMap(
@@ -272,6 +278,49 @@ protected String doApply(
       return resolver.apply(id(), snippetContext);
     }
   },
+  path {
+    @Override
+    protected String doApply(
+        SnippetResolver resolver,
+        OperationExt operation,
+        Map<String, Object> snippetContext,
+        Map<String, Object> args,
+        PebbleTemplate self,
+        EvaluationContext context,
+        int lineNumber) {
+      var namedArgs = positionalArgs(args);
+      // Path
+      var path = parameters(operation, p -> "path".equals(p.getIn()));
+      var pathParams = new HashMap<String, Object>();
+      path.forEach(
+          p -> {
+            pathParams.put(
+                p.getName(), namedArgs.getOrDefault(p.getName(), "{" + p.getName() + "}"));
+          });
+      // QueryString
+      var query =
+          parameters(
+              operation,
+              p ->
+                  "query".equals(p.getIn())
+                      && (namedArgs.isEmpty() || namedArgs.containsKey(p.getName())));
+      var queryString =
+          query.isEmpty()
+              ? ""
+              : query.stream()
+                  .map(
+                      it -> {
+                        var value =
+                            namedArgs.getOrDefault(
+                                it.getName(), SchemaData.shemaType(it.getSchema()));
+                        return it.getName()
+                            + "="
+                            + UrlEscapers.urlFragmentEscaper().escape(value.toString());
+                      })
+                  .collect(Collectors.joining("&", "?", ""));
+      return operation.getPath(pathParams) + queryString;
+    }
+  },
   pathParameters {
     @Override
     protected String doApply(
@@ -406,7 +455,7 @@ protected final String id() {
 
   @Override
   public List<String> getArgumentNames() {
-    return List.of("code");
+    return null;
   }
 
   protected abstract String doApply(
@@ -465,10 +514,10 @@ protected ResponseExt responseByStatusCode(
 
   protected Map<String, Object> newSnippetContext(String serverUrl, OperationExt operation) {
     Map<String, Object> map = new HashMap<>();
-    map.put("pattern", operation.getPattern());
-    map.put("path", operation.getPattern());
+    map.put("pattern", operation.getPath());
+    map.put("path", operation.getPath());
     map.put("method", operation.getMethod());
-    map.put("url", serverUrl + operation.getPattern());
+    map.put("url", serverUrl + operation.getPath());
     var requestHeaders = ArrayListMultimap.<String, String>create();
     var responseHeaders = ArrayListMultimap.<String, String>create();
     var headerParams =
@@ -524,14 +573,17 @@ protected List<Map<String, String>> schemaToTable(Schema<?> schema, EvaluationCo
     return fields;
   }
 
+  protected List<Parameter> parameters(OperationExt operation, Predicate<Parameter> predicate) {
+    return Optional.ofNullable(operation.getParameters()).orElse(List.of()).stream()
+        .filter(predicate)
+        .sorted(Comparator.comparing(Parameter::getName))
+        .toList();
+  }
+
   protected List<Map<String, String>> parametersToTable(
       OperationExt operation, Predicate<Parameter> predicate) {
     List<Map<String, String>> fields = new ArrayList<>();
-    var parameters =
-        Optional.ofNullable(operation.getParameters()).orElse(List.of()).stream()
-            .filter(predicate)
-            .sorted(Comparator.comparing(Parameter::getName))
-            .toList();
+    var parameters = parameters(operation, predicate);
     parameters.forEach(
         it -> {
           var schema = it.getSchema();
@@ -601,27 +653,36 @@ protected Multimap<CharSequence, String> parseHeaders(Collection<String> headers
   protected static final Set<String> READ_METHODS = Set.of("GET", "HEAD");
 
   protected String toString(Multimap<String, String> options) {
-    if (options.isEmpty()) {
-      return "";
-    }
     var sb = new StringBuilder();
     var separator = "\\\n";
     var tabSize = id().length() + 1;
-    options.forEach(
-        (k, v) -> {
-          if (!sb.isEmpty()) {
-            sb.append(" ".repeat(tabSize));
-          }
-          sb.append(k);
-          if (v != null && !v.isEmpty()) {
-            sb.append(" ").append(v);
-          }
-          sb.append(separator);
-        });
+    for (Map.Entry<String, String> entry : options.entries()) {
+      var k = entry.getKey();
+      var v = entry.getValue();
+      if (!sb.isEmpty()) {
+        sb.append(" ".repeat(tabSize));
+      }
+      sb.append(k);
+      if (v != null && !v.isEmpty()) {
+        sb.append(" ").append(v);
+      }
+      sb.append(separator);
+    }
     sb.setLength(sb.length() - separator.length());
     return sb.toString();
   }
 
+  protected Map<String, Object> positionalArgs(Map<String, Object> args) {
+    var optionList = new ArrayList<>(args.values());
+    Map<String, Object> result = new LinkedHashMap<>();
+    for (int i = 0; i < optionList.size(); i += 2) {
+      var key = optionList.get(i).toString();
+      var value = optionList.get(i + 1);
+      result.put(key, value);
+    }
+    return result;
+  }
+
   protected Multimap<String, String> args(Map<String, Object> args) {
     Multimap<String, String> result = LinkedHashMultimap.create();
     var optionList = new ArrayList<>(args.values());

modules/jooby-openapi/src/main/java/io/jooby/openapi/OpenAPIGenerator.java

@@ -265,7 +265,7 @@ public OpenAPIGenerator() {}
     Map<String, Tag> globalTags = new LinkedHashMap<>();
     Paths paths = new Paths();
     for (OperationExt operation : operations) {
-      String pattern = operation.getPattern();
+      String pattern = operation.getPath();
       if (!includes(pattern) || excludes(pattern)) {
         log.debug("skipping {}", pattern);
         continue;

modules/jooby-openapi/src/main/resources/io/jooby/openapi/templates/asciidoc/default-cookie-parameters.snippet

@@ -1,3 +1,4 @@
+[cols="1,3"]
 |===
 |Parameter|Description
 {% for cookie in cookies %}

modules/jooby-openapi/src/main/resources/io/jooby/openapi/templates/asciidoc/default-curl.snippet

@@ -1,4 +1,4 @@
-[source,bash]
+[source{% if language %}, ${language}{%endif%}]
 ----
 curl ${options}
 ----

modules/jooby-openapi/src/main/resources/io/jooby/openapi/templates/asciidoc/default-form-parameters.snippet

@@ -1,3 +1,4 @@
+  [cols="1,1,3"]
 |===
 |Parameter|Type|Description
 {% for parameter in parameters %}

modules/jooby-openapi/src/main/resources/io/jooby/openapi/templates/asciidoc/default-path-parameters.snippet

@@ -1,3 +1,4 @@
+  [cols="1,1,3"]
 |===
 |Parameter|Type|Description
 {% for parameter in parameters %}