Support definitions that don't have tags. Closes #140

README.md

@@ -53,11 +53,11 @@ You need to specify a url for the `Open API v3` file, e.g. <http://localhost:820
 
 The following configuration options apply to the Lincoln component:
 
-| property        | required | type    | description                                                                                                         |
-| --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
-| `definitionUrl` | ✔        | string  | CORS-enabled URL to Open API v3 definition to render. Supports JSON or YAML.                                        |
-| `navSort`       |          | enum    | `alpha` which sorts by HTTP method, then path or `false`, which will display paths as defined. Defaults to `false`. |
-| `validate`      |          | boolean | If `true`, uses [Mermade](https://openapi-converter.herokuapp.com/) to validate definition. Defaults to `false`.    |
+| property        | required | type    | description                                                                                                                                                                 |
+| --------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `definitionUrl` | ✔        | string  | CORS-enabled URL to Open API v3 definition to render. Supports JSON or YAML.                                                                                                |
+| `navSort`       |          | enum    | This property applies when your definition uses `tags`. `alpha` which sorts by HTTP method, then path or `false`, which will display paths as defined. Defaults to `false`. |
+| `validate`      |          | boolean | If `true`, uses [Mermade](https://openapi-converter.herokuapp.com/) to validate definition. Defaults to `false`.                                                            |
 
 ## Building & Deployment
 

docs/open-api-v3-support.md

@@ -101,7 +101,7 @@ This is supported by default as all `$ref` are dereferenced before the definitio
 
 ### [Operation](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#operation-object) object
 
-- [x] tags - Currently *required* for this project.
+- [x] tags
 - [x] summary
 - [x] description
 - [ ] [externalDocs](#external-documentation-object)

package.json

@@ -82,11 +82,11 @@
     "babel-regenerator-runtime": "^6.5.0",
     "babel-runtime": "^6.23.0",
     "css-loader": "^0.28.4",
-    "eslint": "^4.0.0",
+    "eslint": "^4.1.0",
     "eslint-config-standard": "^10.2.1",
     "eslint-config-standard-react": "^5.0.0",
-    "eslint-plugin-import": "^2.3.0",
-    "eslint-plugin-node": "^5.0.0",
+    "eslint-plugin-import": "^2.6.0",
+    "eslint-plugin-node": "^5.1.0",
     "eslint-plugin-promise": "^3.5.0",
     "eslint-plugin-react": "^7.0.1",
     "eslint-plugin-standard": "^3.0.1",

src/components/Navigation/Navigation.js

@@ -2,6 +2,7 @@ import React, { Component } from 'react'
 import PropTypes from 'prop-types'
 import isEqual from 'lodash/isEqual'
 import NavigationTag from '../NavigationTag/NavigationTag'
+import NavigationMethod from '../NavigationMethod/NavigationMethod'
 import { styles } from './Navigation.styles'
 
 @styles
@@ -30,18 +31,22 @@ export default class Navigation extends Component {
     return (
       <nav className={classes.navigation}>
         {navigation && navigation.map((tag) => {
-          let shouldBeExpanded = false
-          if (expandedTags.includes(tag.title)) {
-            shouldBeExpanded = true
+          // Handle a navigation that doesn't require tags.
+          if (!tag.methods) {
+            const isActive = (`#${tag.link}` === location.hash)
+            return (
+              <NavigationMethod key={tag.link} method={tag} isActive={isActive} isOpen />
+            )
           }
 
+          // Otherwise the navigation is grouped by tag.
           return (
             <NavigationTag
               key={tag.title}
               title={tag.title}
               description={tag.description}
               methods={tag.methods}
-              shouldBeExpanded={shouldBeExpanded}
+              shouldBeExpanded={expandedTags.includes(tag.title)}
               onClick={this.onClick}
               hash={hash}
             />

src/components/Navigation/Navigation.styles.js

@@ -19,6 +19,10 @@ export const styles = createSheet(({ backgrounds }) => ({
 
     '& > div + div': {
       borderTop: '1px solid #444'
+    },
+
+    '& > a': {
+      padding: '.7rem 1rem'
     }
   }
 }))

src/parser/open-api/v3/navigationParser.js

@@ -0,0 +1,60 @@
+/**
+ * Return the permalink for the given `path` and `methodType`. Note this is
+ * not the link to the actual path, but it's a unique identifier to help
+ * with deeplinking from UI applications.
+ *
+ * @todo Look at supporting `operationId` which does this purpose.
+ * @param {string} path
+ * @param {string} methodType
+ */
+function getPermalink (path, methodType) {
+  return `${path}/${methodType}`
+}
+
+/**
+ * Given the `path`, `method` and optionally the `tag`, construct
+ * an object that represents the navigation method.
+ *
+ * @param {string} path
+ * @param {object} method
+ * @param {object} tag
+ * @return {object}
+ */
+export function getNavigationMethod (path, method, tag) {
+  return {
+    type: method.type,
+    title: method.summary,
+    link: getPermalink(path, method.type)
+  }
+}
+
+/**
+ * Construct the object used to render the method in the body of the renderer.
+ * This should represent all the information to create a request and receive
+ * a response for the given `method`.
+ *
+ * @param {string} path
+ * @param {object} method
+ * @param {object} request
+ * @param {object} params
+ * @param {object} responses
+ */
+export function getServicesMethod ({ path, method, request, params, responses }) {
+  const servicesMethod = {
+    type: method.type,
+    title: method.summary,
+    link: getPermalink(path, method.type),
+    request,
+    responses
+  }
+
+  if (method.description) {
+    servicesMethod.description = method.description
+  }
+
+  if (params) {
+    servicesMethod.parameters = params
+  }
+
+  return servicesMethod
+}

src/parser/open-api/v3/open-api-v3-parser.js

@@ -1,90 +1,123 @@
 import refParser from 'json-schema-ref-parser'
 import { getSecurityDefinitions, getUISecurity } from './securityParser'
+import { getNavigationMethod, getServicesMethod } from './navigationParser'
 import getUIReadySchema from '../schemaParser'
 
 /**
  * Construct navigation and services ready to be consumed by the UI
  *
+ * @param {Object} paths
+ * @param {Array} apiSecurity
+ * @param {Object} securityDefinitions
+ * @return {{navigation: [], services: []}}
+ */
+function getUINavigationAndServices ({ paths, apiSecurity = [], securityDefinitions }) {
+  const { navigationMethods: navigation, servicesMethods } =
+    buildNavigationAndServices(paths, apiSecurity, securityDefinitions)
+
+  // Need to wrap up the methods to be individual services blocks.
+  // This simplifies the component logic.
+  const services = servicesMethods.map(method => {
+    return {
+      title: method.title,
+      methods: [ method ]
+    }
+  })
+
+  return {navigation, services}
+}
+
+/**
+ * Construct navigation and services ready to be consumed by the UI using tags.
+ * This will group the paths by the logical tags.
+ *
  * @param {Array} tags
  * @param {Object} paths
  * @param {Array} apiSecurity
  * @param {Object} securityDefinitions
  * @param {Function} sortFunc
  * @return {{navigation: [], services: []}}
  */
-function getUINavigationAndServices ({ tags, paths, apiSecurity = [], securityDefinitions, sortFunc }) {
+function getUINavigationAndServicesByTags ({ tags, paths, apiSecurity = [], securityDefinitions, sortFunc }) {
   const navigation = []
   const services = []
+  const isFunc = typeof sortFunc === 'function'
 
-  for (let i = 0; i < tags.length; i++) {
+  for (let i = 0, tagLength = tags.length; i < tagLength; i++) {
     const tag = tags[i]
-    const navigationMethods = []
-    const servicesMethods = []
-    const pathIds = Object.keys(paths)
-
-    for (let j = 0; j < pathIds.length; j++) {
-      const pathId = pathIds[j]
-      const path = paths[pathId]
-      const methodTypes = Object.keys(path)
+    const exclusionFunc = (method) => method.tags.includes(tag) === false
+    const { navigationMethods, servicesMethods } =
+      buildNavigationAndServices(paths, apiSecurity, securityDefinitions, exclusionFunc)
 
-      for (let k = 0; k < methodTypes.length; k++) {
-        const methodType = methodTypes[k]
-        const method = path[methodType]
+    navigation.push({
+      title: tag,
+      methods: isFunc ? navigationMethods.sort(sortFunc) : navigationMethods
+    })
 
-        if (!method.tags.includes(tag)) {
-          continue
-        }
+    services.push({
+      title: tag,
+      methods: isFunc ? servicesMethods.sort(sortFunc) : servicesMethods
+    })
+  }
 
-        const link = pathId + '/' + methodType
-        const navigationMethod = {
-          type: methodType,
-          title: method.summary,
-          link
-        }
-        navigationMethods.push(navigationMethod)
-
-        const uiRequest = getUIRequest(method.description, method.requestBody)
-        const uiResponses = getUIResponses(method.responses)
-        const servicesMethod = {
-          type: methodType,
-          title: method.summary,
-          link,
-          request: uiRequest,
-          responses: uiResponses
-        }
+  return { navigation, services }
+}
 
-        if (method.description) {
-          servicesMethod.description = method.description
-        }
+/**
+ * Build the navigation and services from the given paths.
+ * Optionally run an `exclusionFunc` which if returns true, will skip
+ * the path from being included in the result.
+ *
+ * @param {Object} paths
+ * @param {Array} apiSecurity
+ * @param {Object} securityDefinitions
+ * @param {Function} exclusionFunc
+ * @return {{navigation: [], services: []}}
+ */
+function buildNavigationAndServices (paths, apiSecurity, securityDefinitions, exclusionFunc) {
+  const pathIds = Object.keys(paths)
+  const navigationMethods = []
+  const servicesMethods = []
+  const isFunc = typeof exclusionFunc === 'function'
+
+  for (let j = 0, pathIdLength = pathIds.length; j < pathIdLength; j++) {
+    const pathId = pathIds[j]
+    const path = paths[pathId]
+    const methodTypes = Object.keys(path)
+
+    for (let k = 0, methodLength = methodTypes.length; k < methodLength; k++) {
+      const methodType = methodTypes[k]
+      const method = Object.assign({ type: methodType }, path[methodType])
+
+      // Should this be included in the output?
+      if (isFunc && exclusionFunc(method)) {
+        continue
+      }
 
-        // Security can be declared per method, or globally for the entire API.
-        if (method.security) {
-          servicesMethod.security = getUISecurity(method.security, securityDefinitions)
-        } else if (apiSecurity.length) {
-          servicesMethod.security = getUISecurity(apiSecurity, securityDefinitions)
-        }
+      // Add the navigation item
+      navigationMethods.push(getNavigationMethod(pathId, method))
 
-        const uiParameters = getUIParameters(method.parameters)
-        if (uiParameters) {
-          servicesMethod.parameters = uiParameters
-        }
+      // Construct the full method object
+      const servicesMethod = getServicesMethod({
+        path: pathId,
+        method,
+        request: getUIRequest(method.description, method.requestBody),
+        params: getUIParameters(method.parameters),
+        responses: getUIResponses(method.responses)
+      })
 
-        servicesMethods.push(servicesMethod)
+      // Security can be declared per method, or globally for the entire API.
+      if (method.security) {
+        servicesMethod.security = getUISecurity(method.security, securityDefinitions)
+      } else if (apiSecurity.length) {
+        servicesMethod.security = getUISecurity(apiSecurity, securityDefinitions)
       }
-    }
 
-    navigation.push({
-      title: tag,
-      methods: typeof sortFunc === 'function' ? navigationMethods.sort(sortFunc) : navigationMethods
-    })
-
-    services.push({
-      title: tag,
-      methods: typeof sortFunc === 'function' ? servicesMethods.sort(sortFunc) : servicesMethods
-    })
+      servicesMethods.push(servicesMethod)
+    }
   }
 
-  return {navigation, services}
+  return { navigationMethods, servicesMethods }
 }
 
 /**
@@ -277,6 +310,10 @@ function getTags (paths) {
     for (const methodKey in path) {
       const method = path[methodKey]
 
+      if (Array.isArray(method.tags) === false) {
+        continue
+      }
+
       method.tags.forEach(tag => {
         if (!tagCollection.includes(tag)) {
           tagCollection.push(tag)
@@ -334,23 +371,16 @@ export default async function getUIReadyDefinition (openApiV3, sortFunc) {
   const info = derefOpenApiV3.info
   const paths = derefOpenApiV3.paths
   const apiSecurity = derefOpenApiV3.security || []
-
-  // Get tags from the paths
-  const tags = getTags(paths)
-
-  // Get security definitions
   const securityDefinitions = getSecurityDefinitions(derefOpenApiV3)
 
-  // Construction navigation and services
-  const {navigation, services} = getUINavigationAndServices({
-    tags,
-    paths,
-    apiSecurity,
-    securityDefinitions,
-    sortFunc
-  })
+  // Construct navigation and services, which differs depending on
+  // if the definition utilises tags or not.
+  const tags = getTags(paths)
+  const {navigation, services} = (tags.length)
+    ? getUINavigationAndServicesByTags({ tags, paths, apiSecurity, securityDefinitions, sortFunc })
+    : getUINavigationAndServices({ paths, apiSecurity, securityDefinitions })
 
-  // If we have tag information, let's add it to the navigation
+  // If we have top-level tag descriptions, add it to the navigation
   if (derefOpenApiV3.tags) {
     addTagDetailsToNavigation(navigation, derefOpenApiV3.tags)
   }