organize the swagger spec by tag

Tags show up in the swagger-ui doc renderer as groups of routes. This is basically a requirement in order for it to look useful. Otherwise they all show up under a strange heading called "default" which requires a click through and is incredibly confusing...
cpan-testers · Dec 24, 2016 · 63bff23 · 63bff23
1 parent 3f0a22f
commit 63bff23
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 15 deletions.
diff --git a/share/api.json b/share/api.json
@@ -9,12 +9,23 @@
     "produces": [ "application/json" ],
     "schemes": [ "http" ],
     "basePath": "/v1",
+    "tags": [
+        {
+            "name": "Release",
+            "description": "Per-release test summary data"
+        },
+        {
+            "name": "Upload",
+            "description": "CPAN uploads data"
+        }
+    ],
 
     "paths": {
         "/release": {
             "get": {
-                "operationId": "release",
-                "description": "Get summary test report information about CPAN releases",
+                "tags": [ "Release" ],
+                "operationId": "release_all",
+                "summary": "Get summary test report info about all CPAN releases",
                 "x-mojo-to": {
                     "controller": "Release",
                     "action": "release"
@@ -37,8 +48,9 @@
 
         "/release/dist/{dist}": {
             "get": {
+                "tags": [ "Release" ],
                 "operationId": "release_dist",
-                "description": "Get summary test report information about CPAN releases for a particular distribution",
+                "summary": "Get summary test report info for releases of a distribution",
                 "x-mojo-to": {
                     "controller": "Release",
                     "action": "release"
@@ -65,8 +77,9 @@
 
         "/release/author/{author}": {
             "get": {
+                "tags": [ "Release" ],
                 "operationId": "release_author",
-                "description": "Get summary test report information about CPAN releases for a particular author",
+                "summary": "Get summary test report info for releases by an author",
                 "x-mojo-to": {
                     "controller": "Release",
                     "action": "release"
@@ -93,8 +106,10 @@
 
         "/upload": {
             "get": {
-                "operationId": "upload",
-                "description": "Query the uploads to CPAN. Asking for a WebSocket will subscribe to a feed of new uploads.",
+                "tags": [ "Upload" ],
+                "operationId": "upload_all",
+                "summary": "Get all uploads to CPAN",
+                "description": "This route gets uploads to CPAN. Asking for a WebSocket will subscribe to a feed of new uploads.",
                 "x-mojo-to": {
                     "controller": "Upload",
                     "action": "get"
@@ -120,8 +135,10 @@
 
         "/upload/dist/{dist}": {
             "get": {
+                "tags": [ "Upload" ],
                 "operationId": "upload_dist",
-                "description": "Get the uploads for the given dist. Asking for a WebSocket will subscribe to a feed of new uploads.",
+                "summary": "Get uploads for a dist",
+                "description": "This route gets uploads to CPAN for a specific distribution. Asking for a WebSocket will subscribe to a feed of new uploads.",
                 "x-mojo-to": {
                     "controller": "Upload",
                     "action": "get"
@@ -148,8 +165,10 @@
 
         "/upload/author/{author}": {
             "get": {
+                "tags": [ "Upload" ],
                 "operationId": "upload_author",
-                "description": "Get the uploads for the given author. Asking for a WebSocket will subscribe to a feed of new uploads.",
+                "summary": "Get uploads for an author",
+                "description": "This route gets uploads to CPAN for the specific author. Asking for a WebSocket will subscribe to a feed of new uploads.",
                 "x-mojo-to": {
                     "controller": "Upload",
                     "action": "get"

diff --git a/share/templates/index.html.ep b/share/templates/index.html.ep
@@ -45,16 +45,16 @@
 
             <ul>
             <li>Test report summaries (releases) for <a
-            href="/docs/?url=/v1#!/default/release">all of CPAN</a>,
-            <a href="/docs/?url=/v1#!/default/release_author">by
+            href="/docs/?url=/v1#!/Release/all">all of CPAN</a>,
+            <a href="/docs/?url=/v1#!/Release/author">by
             author</a>, or <a
-            href="/docs/?url=/v1#!/default/release_dist">by
+            href="/docs/?url=/v1#!/Release/dist">by
             distribution</a>.</li>
             <li>CPAN uploads for <a
-            href="/docs/?url=/v1#!/default/upload">all of CPAN</a>,
-            <a href="/docs/?url=/v1#!/default/upload_author">by
+            href="/docs/?url=/v1#!/Upload/all">all of CPAN</a>,
+            <a href="/docs/?url=/v1#!/Upload/author">by
             author</a>, or <a
-            href="/docs/?url=/v1#!/default/upload_dist">by
+            href="/docs/?url=/v1#!/Upload/dist">by
             distribution</a>. Subscribing to these using a WebSocket
             will enable push notifications of new uploads to CPAN (see
             <a
@@ -69,7 +69,7 @@
             </ul>
 
             <p>For full documentation on the available APIs, see <a
-            href="/docs/?url=/v1#/default">the API documentation</a>.</p>
+            href="/docs/?url=/v1">the API documentation</a>.</p>
 
             If you'd like to help contribute to the CPAN Testers API,
             visit <a