Wire up event documentation generation

jenkinsci · Jul 27, 2016 · 69956d8 · 69956d8
1 parent 22936a5
commit 69956d8
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 4 deletions.
diff --git a/src/main/java/hudson/plugins/tfs/TeamWebHook.java b/src/main/java/hudson/plugins/tfs/TeamWebHook.java
@@ -30,6 +30,7 @@
 import org.acegisecurity.context.SecurityContextHolder;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.lang.StringUtils;
+import org.apache.commons.lang3.StringEscapeUtils;
 import org.eclipse.jgit.transport.RemoteConfig;
 import org.eclipse.jgit.transport.URIish;
 import org.kohsuke.stapler.HttpResponse;
@@ -96,16 +97,36 @@ public String getUrlName() {
     public HttpResponse doIndex(final HttpServletRequest request) throws IOException {
         final Class<? extends TeamWebHook> me = this.getClass();
         final InputStream stream = me.getResourceAsStream("TeamWebHook.html");
+        final Jenkins instance = Jenkins.getInstance();
+        final String rootUrl = instance.getRootUrl();
+        final String eventRows = describeEvents(HOOK_EVENT_FACTORIES_BY_NAME, URL_NAME);
         try {
             final String template = IOUtils.toString(stream, MediaType.UTF_8);
-            final String content = String.format(template, URL_PREFIX, "TODO: event names");
+            final String content = String.format(template, URL_NAME, eventRows, rootUrl);
             return HttpResponses.html(content);
         }
         finally {
             IOUtils.closeQuietly(stream);
         }
     }
 
+    static String describeEvents(final Map<String, AbstractHookEvent.Factory> eventMap, final String urlName) {
+        final String newLine = System.getProperty("line.separator");
+        final StringBuilder sb = new StringBuilder();
+        for (final Map.Entry<String, AbstractHookEvent.Factory> eventPair : eventMap.entrySet()) {
+            final String eventName = eventPair.getKey();
+            final AbstractHookEvent.Factory factory = eventPair.getValue();
+            sb.append("<tr>").append(newLine);
+            sb.append("<td valign='top'>").append(eventName).append("</td>").append(newLine);
+            sb.append("<td valign='top'>").append('/').append(urlName).append('/').append(eventName).append("</td>").append(newLine);
+            final String rawSample = factory.getSampleRequestPayload();
+            final String escapedSample = StringEscapeUtils.escapeHtml4(rawSample);
+            sb.append("<td><pre>").append(escapedSample).append("</pre></td>").append(newLine);
+            sb.append("</tr>").append(newLine);
+        }
+        return sb.toString();
+    }
+
     static String pathInfoToEventName(final String pathInfo) {
         if (pathInfo.startsWith(URL_PREFIX)) {
             final String restOfPath = pathInfo.substring(URL_PREFIX.length());

diff --git a/src/main/resources/hudson/plugins/tfs/TeamWebHook.html b/src/main/resources/hudson/plugins/tfs/TeamWebHook.html
@@ -1,7 +1,30 @@
 <html>
     <body>
-        <h1>The <code>%1$s</code> endpoint</h1>
+        <h1>The <code>/%1$s/</code> endpoint</h1>
+        <h2>Events</h2>
+        The following events are available to POST to:
+        <table border="1">
+            <tr>
+                <th>Name</th>
+                <th>Path</th>
+                <th>Sample payload</th>
+            </tr>
+%2$s
+        </table>
+        <h2>Example</h2>
+        Suppose we have a Jenkins server at <code>%3$s</code> and the following <code>payload.json</code> file:
+        <pre>
+{
+    "message": "Hello, world!"
+}
+        </pre>
+        The following example demonstrates a POST to the <code>ping</code> event using the <a href="https://curl.haxx.se/">curl</a> tool:
+        <pre>
+curl --request POST %3$s%1$s/ping --header 'Content-Type: application/json' --data-binary @payload.json
+        </pre>
+        The console output should look like the following when the <code>ping</code> event from the <code>%1$s</code> endpoint returns the provided payload, formatted for compactness:
+        <pre>
+{"message":"Hello, world!"}
+        </pre>
     </body>
-    The following events are available:
-    %2$s
 </html>