Use 'hapi-swagger' to expose swagger endpoint documenting plugin routes

elastic · Jul 1, 2019 · 5301b2c · 5301b2c
1 parent 6283efa
commit 5301b2c
Show file tree

Hide file tree

Showing 7 changed files with 67 additions and 22 deletions.
diff --git a/package.json b/package.json
@@ -169,6 +169,7 @@
     "handlebars": "4.1.2",
     "hapi": "^17.5.3",
     "hapi-auth-cookie": "^9.0.0",
+    "hapi-swaggered": "^3.0.3",
     "hjson": "3.1.2",
     "hoek": "^5.0.4",
     "http-proxy-agent": "^2.1.0",

diff --git a/x-pack/legacy/plugins/integrations_manager/common/constants.ts b/x-pack/legacy/plugins/integrations_manager/common/constants.ts
@@ -6,6 +6,7 @@
 import manifest from '../kibana.json';
 
 export const PLUGIN_ID = manifest.id;
+export const PLUGIN_VERSION = manifest.version;
 export const SAVED_OBJECT_TYPE = 'integrations-manager';
 export const API_ROOT = `/api/${PLUGIN_ID}`;
 export const API_INTEGRATIONS_LIST = `${API_ROOT}/list`;

diff --git a/x-pack/legacy/plugins/integrations_manager/schemas/consumed/list.schema.json b/x-pack/legacy/plugins/integrations_manager/schemas/consumed/list.schema.json
@@ -1,11 +1,14 @@
 {
     "$schema": "http://json-schema.org/draft-06/schema#",
-    "type": "array",
-    "items": {
-        "$ref": "#/definitions/ListElement"
-    },
+    "$ref": "#/definitions/IntegrationList",
     "definitions": {
-        "ListElement": {
+        "IntegrationList": {
+          "type": "array",
+          "items": {
+              "$ref": "#/definitions/IntegrationListElement"
+          }
+        },
+        "IntegrationListElement": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
@@ -32,7 +35,7 @@
                 "name",
                 "version"
             ],
-            "title": "ListElement"
+            "title": "IntegrationListElement"
         }
     }
 }
diff --git a/x-pack/legacy/plugins/integrations_manager/server/plugin.ts b/x-pack/legacy/plugins/integrations_manager/server/plugin.ts
@@ -4,7 +4,9 @@
  * you may not use this file except in compliance with the Elastic License.
  */
 
+import HapiSwagger from 'hapi-swaggered';
 import { HttpServiceSetup, CoreStart } from 'src/core/server';
+import { API_ROOT, PLUGIN_ID, PLUGIN_VERSION } from '../common/constants';
 import { fetchList } from './registry';
 import { routes } from './routes';
 
@@ -23,6 +25,21 @@ export class Plugin {
   public setup(core: CoreSetup) {
     const { server } = core.http;
 
+    server.register([
+      {
+        plugin: HapiSwagger,
+        options: {
+          endpoint: `${API_ROOT}/swagger.json`,
+          requiredTags: [`access:${PLUGIN_ID}`, 'api'],
+          info: {
+            title: 'API Documentation',
+            description: 'Description goes here',
+            version: PLUGIN_VERSION,
+          },
+        },
+      },
+    ]);
+
     // map routes to handlers
     routes.forEach(route => server.route(route));
 

diff --git a/x-pack/legacy/plugins/integrations_manager/server/routes.ts b/x-pack/legacy/plugins/integrations_manager/server/routes.ts
@@ -26,22 +26,19 @@ interface PostRequest extends Request {
   };
 }
 
-async function defaultFailureHandler(req, h, err) {
-  if (err) {
-    return h.response(err.message);
-  }
-}
-
 // Manager public API paths (currently essentially a proxy to registry service)
 export const routes: ServerRoute[] = [
   {
     method: 'GET',
     path: API_INTEGRATIONS_LIST,
     options: {
-      tags: [`access:${PLUGIN_ID}`],
+      tags: [`access:${PLUGIN_ID}`, 'api'],
       response: {
-        schema: Enjoi.schema(listSchema),
-        failAction: defaultFailureHandler,
+        // TODO: Figure out why we need .meta and to spread
+        schema: Enjoi.schema({
+          ...listSchema,
+          ...listSchema.definitions.IntegrationListElement,
+        }).meta({ className: 'IntegrationListElement' }),
       },
     },
     handler: fetchList,
@@ -50,22 +47,21 @@ export const routes: ServerRoute[] = [
     method: 'GET',
     path: API_INTEGRATIONS_INFO,
     options: {
-      tags: [`access:${PLUGIN_ID}`],
+      tags: [`access:${PLUGIN_ID}`, 'api'],
       validate: {
         params: {
           pkgkey: Joi.string()
-            // TODO: real validation for name-version
-            // switch to name@version
+            // TODO: real validation for name-semver
             .regex(/\w+-\d+\.\d+\.\d+$/)
             .required(),
         },
       },
       response: {
+        // TODO: Figure out why we need .meta and to spread
         schema: Enjoi.schema({
           ...packageSchema,
           ...packageSchema.definitions.Package,
-        }),
-        failAction: defaultFailureHandler,
+        }).meta({ className: 'Package' }),
       },
     },
     handler: async (req: Request) => fetchInfo(req.params.pkgkey),

diff --git a/x-pack/package.json b/x-pack/package.json
@@ -188,6 +188,7 @@
     "@scant/router": "^0.1.0",
     "@slack/client": "^4.8.0",
     "@turf/boolean-contains": "6.0.1",
+    "@types/hapi__joi": "^15.0.2",
     "angular-resource": "1.4.9",
     "angular-sanitize": "1.6.5",
     "angular-ui-ace": "0.2.3",
@@ -238,6 +239,7 @@
     "h2o2": "^8.1.2",
     "handlebars": "^4.0.14",
     "hapi-auth-cookie": "^9.0.0",
+    "hapi-swaggered": "^3.0.2",
     "history": "4.9.0",
     "history-extra": "^5.0.1",
     "humps": "2.0.1",

diff --git a/yarn.lock b/yarn.lock
@@ -3672,6 +3672,13 @@
     "@types/podium" "*"
     "@types/shot" "*"
 
+"@types/hapi__joi@*", "@types/hapi__joi@^15.0.2":
+  version "15.0.2"
+  resolved "https://registry.yarnpkg.com/@types/hapi__joi/-/hapi__joi-15.0.2.tgz#94f37e9afab4db6a03f3d9e80dc939eb1f7b9a4f"
+  integrity sha512-EsOuX8cbAdSgp/9mo5NoI4vMnZ68c8Jk1fl3tyA07zd9aOq4q4udsJ2/YjhaFw0u2Zp6hBonUBrKEWotZg7PDQ==
+  dependencies:
+    "@types/hapi__joi" "*"
+
 "@types/has-ansi@^3.0.0":
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/@types/has-ansi/-/has-ansi-3.0.0.tgz#636403dc4e0b2649421c4158e5c404416f3f0330"
@@ -14147,6 +14154,24 @@ hapi-auth-cookie@^9.0.0:
     hoek "5.x.x"
     joi "13.x.x"
 
+hapi-swaggered@^3.0.2:
+  version "3.0.2"
+  resolved "https://registry.yarnpkg.com/hapi-swaggered/-/hapi-swaggered-3.0.2.tgz#aaa634cc9e24f2843a1e4735836edf17597db11c"
+  integrity sha512-+eSleEgkeK2iZJobOxeCkSEsbPxZ95g2mxjssSg6odtNJ5/ILMeMFLWavz6h781hRHaUg8TUFDv9cpb3oqrBgA==
+  dependencies:
+    hoek "^5.0.2"
+    joi "^13.0.2"
+    lodash "^4.17.4"
+
+hapi-swaggered@^3.0.3:
+  version "3.0.3"
+  resolved "https://registry.yarnpkg.com/hapi-swaggered/-/hapi-swaggered-3.0.3.tgz#b179309a92e2c736acb224ab60621bbe341a92ff"
+  integrity sha512-mr2DsUtsspdM2qbeGuJgAXoAB5ZAHtsufJR48BffaRptHv3DxPtvLn6jgAVvNw/xQ1GOadJApd43LGygt99pZQ==
+  dependencies:
+    hoek "^5.0.3"
+    joi "^13.1.2"
+    lodash "^4.17.5"
+
 hapi@^17.5.3:
   version "17.6.0"
   resolved "https://registry.yarnpkg.com/hapi/-/hapi-17.6.0.tgz#158a2276253a8de727be678c4daeb1f73929e588"
@@ -14509,7 +14534,7 @@ [email protected], [email protected]:
   resolved "https://registry.yarnpkg.com/hoek/-/hoek-4.2.1.tgz#9634502aa12c445dd5a7c5734b572bb8738aacbb"
   integrity sha512-QLg82fGkfnJ/4iy1xZ81/9SIJiq1NGFUMGs6ParyjBZr6jW2Ufj/snDqTHixNlHdPNwN2RLVD0Pi3igeK9+JfA==
 
-[email protected], hoek@^5.0.4:
+[email protected], hoek@^5.0.2, hoek@^5.0.3, hoek@^5.0.4:
   version "5.0.4"
   resolved "https://registry.yarnpkg.com/hoek/-/hoek-5.0.4.tgz#0f7fa270a1cafeb364a4b2ddfaa33f864e4157da"
   integrity sha512-Alr4ZQgoMlnere5FZJsIyfIjORBqZll5POhDsF4q64dPuJR6rNxXdDxtHSQq8OXRurhmx+PWYEE8bXRROY8h0w==
@@ -16723,7 +16748,7 @@ jju@~1.4.0:
   resolved "https://registry.yarnpkg.com/jju/-/jju-1.4.0.tgz#a3abe2718af241a2b2904f84a625970f389ae32a"
   integrity sha1-o6vicYryQaKykE+EpiWXDzia4yo=
 
-[email protected], joi@^13.5.2:
+[email protected], joi@^13.0.2, joi@^13.1.2, joi@^13.5.2:
   version "13.7.0"
   resolved "https://registry.yarnpkg.com/joi/-/joi-13.7.0.tgz#cfd85ebfe67e8a1900432400b4d03bbd93fb879f"
   integrity sha512-xuY5VkHfeOYK3Hdi91ulocfuFopwgbSORmIwzcwHKESQhC7w1kD5jaVSPnqDxS2I8t3RZ9omCKAxNwXN5zG1/Q==