Add value body identifier (#560)

Author: delvedor

compiler/model/build-model.ts

@@ -50,7 +50,8 @@ import {
   modelTypeAlias,
   parseVariantNameTag,
   parseVariantsTag,
-  verifyUniqueness
+  verifyUniqueness,
+  parseJsDocTags
 } from './utils'
 
 const specsFolder = join(__dirname, '..', '..', 'specification')
@@ -214,6 +215,14 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
         )
       )]
 
+      const pathAndQueryProperties = (declaration.getMembers() as any[]).flatMap(member => {
+        const property = visitRequestOrResponseProperty(member)
+        if (property.name === 'path_parts' || property.name === 'query_parameters') {
+          return property.properties.map(property => property.name)
+        } else if (property.name === 'body') {
+          return undefined
+        }
+      })
       for (const member of declaration.getMembers()) {
         // we are visiting `path_parts, `query_parameters` or `body`
         assert(
@@ -242,6 +251,22 @@ function compileClassOrInterfaceDeclaration (declaration: ClassDeclaration | Int
               type.body = { kind: 'no_body' }
             } else {
               type.body = { kind: 'value', value: property.valueOf }
+              const openGenerics = declaration.getTypeParameters().map(modelGenerics)
+              if ((property.valueOf.kind === 'instance_of' && openGenerics.includes(property.valueOf.type.name)) ||
+                   property.valueOf.kind === 'array_of') {
+                const tags = parseJsDocTags(member.getJsDocs())
+                assert(
+                  member,
+                  tags.identifier != null,
+                  'You should configure a body @identifier'
+                )
+                assert(
+                  member.getJsDocs(),
+                  !pathAndQueryProperties.includes(tags.identifier),
+                  `The identifier '${tags.identifier}' already exists as a property in the path or query.`
+                )
+                type.body.identifier = tags.identifier
+              }
             }
           } else if (property.properties.length > 0) {
             type.body = { kind: 'properties', properties: property.properties }

compiler/model/metamodel.ts

@@ -265,6 +265,7 @@ export type Body = ValueBody | PropertiesBody | NoBody
 export class ValueBody {
   kind: 'value'
   value: ValueOf
+  identifier?: string
 }
 
 export class PropertiesBody {

docs/modeling-guide.md

@@ -398,3 +398,40 @@ class Foo {
   faz: string
 }
 ```
+
+#### `@identifier`
+
+A custom name that can be used to display the property. Useful in Enums an
+for request bodies where the document is the entire body.
+
+```ts
+export class ConfusionMatrixThreshold {
+  /**
+   * True Positive
+   * @identifier true_positive
+   */
+  tp: integer
+  /**
+   * False Positive
+   * @identifier false_positive
+   */
+  fp: integer
+  /**
+   * True Negative
+   * @identifier true_negative
+   */
+  tn: integer
+  /**
+   * False Negative
+   * @identifier false_negative
+   */
+  fn: integer
+}
+
+export interface Request<TDocument> extends RequestBase {
+  path_parts?: {}
+  query_parameters?: {}
+  /** @identifier document */
+  body?: TDocument
+}
+```

output/schema/schema.json

@@ -12971,6 +12971,7 @@
         "CommonQueryParameters"
       ],
       "body": {
+        "identifier": "operations",
         "kind": "value",
         "value": {
           "kind": "array_of",
@@ -13885,6 +13886,7 @@
         "CommonQueryParameters"
       ],
       "body": {
+        "identifier": "document",
         "kind": "value",
         "value": {
           "kind": "instance_of",
@@ -16865,6 +16867,7 @@
         "CommonQueryParameters"
       ],
       "body": {
+        "identifier": "document",
         "kind": "value",
         "value": {
           "kind": "instance_of",
@@ -17913,6 +17916,7 @@
         "CommonQueryParameters"
       ],
       "body": {
+        "identifier": "searches",
         "kind": "value",
         "value": {
           "kind": "array_of",
@@ -18224,6 +18228,7 @@
         "CommonQueryParameters"
       ],
       "body": {
+        "identifier": "search_templates",
         "kind": "value",
         "value": {
           "kind": "array_of",
@@ -134185,6 +134190,7 @@
     },
     {
       "body": {
+        "identifier": "text_files",
         "kind": "value",
         "value": {
           "kind": "array_of",

specification/_global/bulk/BulkRequest.ts

@@ -52,5 +52,6 @@ export interface Request<TSource> extends RequestBase {
     wait_for_active_shards?: WaitForActiveShards
     require_alias?: boolean
   }
+  /** @identifier operations */
   body?: Array<OperationContainer | TSource>
 }

specification/_global/create/CreateRequest.ts

@@ -51,5 +51,6 @@ export interface Request<TDocument> extends RequestBase {
     version_type?: VersionType
     wait_for_active_shards?: WaitForActiveShards
   }
+  /** @identifier document */
   body?: TDocument
 }

specification/_global/index/IndexRequest.ts

@@ -57,5 +57,6 @@ export interface Request<TDocument> extends RequestBase {
     wait_for_active_shards?: WaitForActiveShards
     require_alias?: boolean
   }
+  /** @identifier document */
   body?: TDocument
 }

specification/_global/msearch/MultiSearchRequest.ts

@@ -87,5 +87,6 @@ export interface Request extends RequestBase {
      */
     typed_keys?: boolean
   }
+  /** @identifier searches */
   body?: Array<Header | Body>
 }

specification/_global/msearch_template/MultiSearchTemplateRequest.ts

@@ -40,5 +40,6 @@ export interface Request extends RequestBase {
     rest_total_hits_as_int?: boolean
     typed_keys?: boolean
   }
+  /** @identifier search_templates */
   body: Array<TemplateItem>
 }

specification/text_structure/find_structure/FindStructureRequest.ts

@@ -68,5 +68,6 @@ export interface Request<TJsonDocument> {
     /** The Java time format of the timestamp field in the text. */
     timestamp_format?: string
   }
+  /** @identifier text_files */
   body: Array<TJsonDocument>
 }