add handling of urls definitions to the compiler

Author: swallez

compiler/src/model/build-model.ts

@@ -53,7 +53,7 @@ import {
   verifyUniqueness,
   parseJsDocTags,
   deepEqual,
-  sourceLocation, sortTypeDefinitions
+  sourceLocation, sortTypeDefinitions, parseDeprecation
 } from './utils'
 
 const jsonSpec = buildJsonSpec()
@@ -210,14 +210,6 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
       if (mapping == null) {
         throw new Error(`Cannot find url template for ${namespace}, very likely the specification folder does not follow the rest-api-spec`)
       }
-      // list of unique dynamic parameters
-      const urlTemplateParams = [...new Set(
-        mapping.urls.flatMap(url => url.path.split('/')
-          .filter(part => part.includes('{'))
-          .map(part => part.slice(1, -1))
-        )
-      )]
-      const methods = [...new Set(mapping.urls.flatMap(url => url.methods))]
 
       let pathMember: Node | null = null
       let bodyProperties: model.Property[] = []
@@ -226,39 +218,50 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
 
       // collect path/query/body properties
       for (const member of declaration.getMembers()) {
-        // we are visiting `path_parts, `query_parameters` or `body`
+        // we are visiting `urls`, `path_parts, `query_parameters` or `body`
         assert(
           member,
           Node.isPropertyDeclaration(member) || Node.isPropertySignature(member),
           'Class and interfaces can only have property declarations or signatures'
         )
-        const property = visitRequestOrResponseProperty(member)
-        if (property.name === 'path_parts') {
+        const name = member.getName()
+        if (name === 'urls') {
+          // Overwrite the endpoint urls read from the json-rest-spec
+          // TODO: once all spec files are using it, make it mandatory.
+          mapping.urls = visitUrls(member)
+        } else if (name === 'path_parts') {
+          const property = visitRequestOrResponseProperty(member)
           assert(member, property.properties.length > 0, 'There is no need to declare an empty object path_parts, just remove the path_parts declaration.')
           pathMember = member
           type.path = property.properties
-        } else if (property.name === 'query_parameters') {
+        } else if (name === 'query_parameters') {
+          const property = visitRequestOrResponseProperty(member)
           assert(member, property.properties.length > 0, 'There is no need to declare an empty object query_parameters, just remove the query_parameters declaration.')
           type.query = property.properties
-        } else if (property.name === 'body') {
+        } else if (name === 'body') {
+          const property = visitRequestOrResponseProperty(member)
           bodyMember = member
-          assert(
-            member,
-            methods.some(method => ['POST', 'PUT', 'DELETE'].includes(method)),
-            `${namespace}.${name} can't have a body, allowed methods: ${methods.join(', ')}`
-          )
           if (property.valueOf != null) {
             bodyValue = property.valueOf
           } else {
             assert(member, property.properties.length > 0, 'There is no need to declare an empty object body, just remove the body declaration.')
             bodyProperties = property.properties
           }
         } else {
-          assert(member, false, `Unknown request property: ${property.name}`)
+          assert(member, false, `Unknown request property: ${name}`)
         }
       }
 
       // validate path properties
+      // list of unique dynamic parameters
+      const urlTemplateParams = [...new Set(
+        mapping.urls.flatMap(url => url.path.split('/')
+          .filter(part => part.includes('{'))
+          .map(part => part.slice(1, -1))
+        )
+      )]
+      const methods = [...new Set(mapping.urls.flatMap(url => url.methods))]
+
       for (const part of type.path) {
         assert(
           pathMember as Node,
@@ -282,6 +285,13 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
       }
 
       // validate body
+      if (bodyMember != null) {
+        assert(
+          bodyMember,
+          methods.some(method => ['POST', 'PUT', 'DELETE'].includes(method)),
+            `${namespace}.${name} can't have a body, allowed methods: ${methods.join(', ')}`
+        )
+      }
       // the body can either be a value (eg Array<string> or an object with properties)
       if (bodyValue != null) {
         // Propagate required body value nature based on TS question token being present.
@@ -587,3 +597,80 @@ function visitRequestOrResponseProperty (member: PropertyDeclaration | PropertyS
 
   return { name, properties, valueOf }
 }
+
+/**
+ * Parse the 'urls' property of a request definition. Format is:
+ * ```
+ * urls: [
+ *   {
+ *     /** @deprecated 1.2.3 Use something else
+ *     path: '/some/path',
+ *     methods: ["GET", "POST"]
+ *   }
+ * ]
+ * ```
+ */
+function visitUrls (member: PropertyDeclaration | PropertySignature): model.UrlTemplate[] {
+  const value = member.getTypeNode()
+
+  // Literal arrays are exposed as tuples by ts-morph
+  assert(value, Node.isTupleTypeNode(value), '"urls" should be an array')
+
+  const result: model.UrlTemplate[] = []
+
+  value.forEachChild(urlNode => {
+    assert(urlNode, Node.isTypeLiteral(urlNode), '"urls" members should be objects')
+
+    const urlTemplate: any = {}
+
+    urlNode.forEachChild(node => {
+      assert(node, Node.isPropertySignature(node), "Expecting 'path' and 'methods' properties")
+
+      const name = node.getName()
+      const propValue = node.getTypeNode()
+
+      if (name === 'path') {
+        assert(propValue, Node.isLiteralTypeNode(propValue), '"path" should be a string')
+
+        const pathLit = propValue.getLiteral()
+        assert(pathLit, Node.isStringLiteral(pathLit), '"path" should be a string')
+
+        urlTemplate.path = pathLit.getLiteralValue()
+
+        // Deprecation
+        const jsDoc = node.getJsDocs()
+        const tags = parseJsDocTags(jsDoc)
+        const deprecation = parseDeprecation(tags, jsDoc)
+        if (deprecation != null) {
+          urlTemplate.deprecation = deprecation
+        }
+        if (Object.keys(tags).length > 0) {
+          assert(jsDoc, false, `Unknown annotations: ${Object.keys(tags).join(', ')}`)
+        }
+      } else if (name === 'methods') {
+        assert(propValue, Node.isTupleTypeNode(propValue), '"methods" should be an array')
+
+        const methods: string[] = []
+        propValue.forEachChild(node => {
+          assert(node, Node.isLiteralTypeNode(node), '"methods" should contain strings')
+
+          const nodeLit = node.getLiteral()
+          assert(nodeLit, Node.isStringLiteral(nodeLit), '"methods" should contain strings')
+
+          methods.push(nodeLit.getLiteralValue())
+        })
+        assert(node, methods.length > 0, "'methods' should not be empty")
+        urlTemplate.methods = methods
+      } else {
+        assert(node, false, "Expecting 'path' or 'methods'")
+      }
+    })
+
+    assert(urlTemplate, urlTemplate.path, "Missing required property 'path'")
+    assert(urlTemplate, urlTemplate.methods, "Missing required property 'methods'")
+
+    result.push(urlTemplate)
+  })
+
+  return result
+}

compiler/src/model/utils.ts

@@ -576,12 +576,21 @@ export function modelProperty (declaration: PropertySignature | PropertyDeclarat
  * Pulls @deprecated from types and properties
  */
 function setDeprecated (type: model.BaseType | model.Property | model.EnumMember, tags: Record<string, string>, jsDocs: JSDoc[]): void {
+  const deprecation = parseDeprecation(tags, jsDocs)
+  if (deprecation != null) {
+    type.deprecation = deprecation
+  }
+}
+
+export function parseDeprecation (tags: Record<string, string>, jsDocs: JSDoc[]): model.Deprecation | undefined {
   if (tags.deprecated !== undefined) {
     const [version, ...description] = tags.deprecated.split(' ')
     assert(jsDocs, semver.valid(version), 'Invalid semver value')
-    type.deprecation = { version, description: description.join(' ') }
+    delete tags.deprecated
+    return { version, description: description.join(' ') }
+  } else {
+    return undefined
   }
-  delete tags.deprecated
 }
 
 /**

compiler/src/steps/validate-rest-spec.ts

@@ -21,6 +21,7 @@ import assert from 'assert'
 import * as model from '../model/metamodel'
 import { JsonSpec } from '../model/json-spec'
 import { ValidationErrors } from '../validation-errors'
+import { deepEqual } from '../model/utils'
 
 // This code can be simplified once https://github.com/tc39/proposal-set-methods is available
 
@@ -46,6 +47,30 @@ export default async function validateRestSpec (model: model.Model, jsonSpec: Ma
       const spec = jsonSpec.get(endpoint.name)
       assert(spec, `Can't find the json spec for ${endpoint.name}`)
 
+      // Check URL paths and methods
+      if (spec.url.paths.length !== endpoint.urls.length) {
+        errors.addEndpointError(endpoint.name, 'request', `${endpoint.request.name}: different number of urls in the json spec`)
+      } else {
+        for (const modelUrl of endpoint.urls) {
+          // URL path
+          const restSpecUrl = spec.url.paths.find(path => path.path === modelUrl.path)
+          if (restSpecUrl == null) {
+            errors.addEndpointError(endpoint.name, 'request', `${endpoint.request.name}: url path '${modelUrl.path}' not found in the json spec`)
+          } else {
+            // URL methods
+            if (!deepEqual([...restSpecUrl.methods].sort(), [...modelUrl.methods].sort())) {
+              errors.addEndpointError(endpoint.name, 'request', `${modelUrl.path}: different http methods in the json spec`)
+            }
+
+            // Deprecation.
+            if ((restSpecUrl.deprecated != null) !== (modelUrl.deprecation != null)) {
+              errors.addEndpointError(endpoint.name, 'request', `${endpoint.request.name}: different deprecation in the json spec`)
+            }
+          }
+        }
+      }
+
+      // Check url parts
       const urlParts = Array.from(new Set(spec.url.paths
         .filter(path => path.parts != null)
         .flatMap(path => {