Example on URI parameter with included type missing when resolved

[gb-arm]

Take a RAML file with these URI parameters:

main.raml

#%RAML 1.0
title: Uri Parameter Examples

/{inlineUriParam}/{includedUriParam1}/{includedUriParam2}:
  uriParameters:
    inlineUriParam:
      displayName: Inline URI parameter
      description: Description of the inline URI parameter
      type: string
      example: "wibble"
    includedUriParam1:
      description: Description of the inline URI parameter
      type: !include type.raml
    includedUriParam2:
#     description: Description of the inline URI parameter
      type: !include type.raml
  get:
    responses:
      200:
        body:
          application/json:
            type: object

type.raml

#%RAML 1.0 DataType

displayName: Included Type
description: Description of included type
type: string
example: "wobble"

When resolved through the default pipeline, the first and third include the example string and the second doesn't. The displayName does get resolved from the underlying type, but the example (and also any annotations if present, not shown in this minimal example) don't get included. The presence of the overriding description at the point of usage of the type seems to prevent the inclusion of the example from the type. The absence of the description seems to prevent it being present in the output even though it is on the type.

Resolved output:

#%RAML 1.0
title: Uri Parameter Examples
/{inlineUriParam}/{includedUriParam1}/{includedUriParam2}:
  uriParameters:
    inlineUriParam:
      displayName: Inline URI parameter
      description: Description of the inline URI parameter
      type: string
      example: wibble
    includedUriParam1:
      displayName: Included Type
      description: Description of the inline URI parameter
      type: string
    includedUriParam2:
      displayName: Included Type
      type: string
      example: wobble
...

Resolution code:

private static CompletableFuture<BoxedUnit> amfReady = AMF.init();
public static String resolveRaml(
      final String path
  ) throws InterruptedException, ExecutionException, MalformedURLException {
    String url = new File(path).toURI().toURL().toString();

    return amfReady
        .thenCompose(__ -> new Raml10Parser().parseFileAsync(url))
        .thenApply(baseUnit -> new Raml10Resolver().resolve(baseUnit, DEFAULT_PIPELINE()))
        .thenCompose(resolvedBaseUnit -> new Raml10Renderer().generateString(resolvedBaseUnit))
        .get();
  }

[gb-arm]

Same is true for EDITING_PIPELINE(). COMPATIBILITY_PIPELINE() does include the examples and descriptions but with a nested type rather than flattened. Is this intentional?

[arielmirra]

Hi @gb-arm! I've analyzed the behavior you mention and have some clarifications:

1. Compatibility pipeline should only be used when changing API specification, from OAS to RAML for example.

2. when an inheritance is present and there are some fields other than type, the examples are removed as they may no longer be valid after the merge. Examples should be added in the same level as the type keyword in your case.

We're not sure if the case of ONLY having type: !include type.raml should have the examples. I've created an internal ticket to analyze this and we'll let you know when we have updates: https://www.mulesoft.org/jira/browse/APIMF-3503

If the issue is fixed, it'll be in AMF version 5.x.x, so if you're using v4 consider upgrading in the meantime.

NOTE:
Replacing this:

includedUriParam:
    type: !include type.raml

with the inline form includedUriParam: !include type.raml will bring the example field as well as all the rest, as we can be sure it's not an inheritance that requires any merging.

Hope that helps!

[arielmirra]

Hi @gb-arm! issue APIMF-3503 has been solved and the fix will be available in the next AMF release version 5.0.3, releasing next week. Thank you!