OAS 3 query parameter description is lost in RAML 0.8

[postatum]

Consider the code [1], RAML 0.8 output [2] and RAML 1.0 output [3]. Note how the RAML 0.8 output is missing the query parameter def description.

[1]

const amf = require('amf-client-js')

const spec = `{
  "openapi":"3.0.1",
  "info":{
    "title":"API Endpoints",
    "version":"v1"
  },
  "paths":{
    "/api/users":{
      "get":{
        "operationId":"getAllUsers",
        "parameters":[
          {
            "name":"def",
            "in":"query",
            "description":"default parameter description..",
            "required":true,
            "schema":{
              "type":"string"
            }
          }
        ]
      }
    }
  }
}
`

async function main () {
  await amf.AMF.init()
  const model = await (new amf.Oas30Parser()).parseStringAsync(spec)

  const raml08Str = await amf.AMF.raml08Generator().generateString(model)
  console.log(raml08Str)

  const raml10Str = await amf.AMF.raml10Generator().generateString(model)
  console.log(raml10Str)
}

main()

[2]

#%RAML 0.8
title: API Endpoints
version: v1
/api/users:
  get:
    displayName: getAllUsers
    queryParameters:
      def:
        type: string
        required: true

[3]

#%RAML 1.0
title: API Endpoints
version: v1
/api/users:
  get:
    displayName: getAllUsers
    queryParameters:
      def:
        description: default parameter description..
        required: true
        type: string

• Please tell us about your environment:

  • AMF Version: 4.2.0
  • AMF Distribution: JS
  • Operating System: Linux

• Other information:
  Originally reported in Question: Possible to exclude endpoints when converting OAS > RAML? raml-org/webapi-parser#81 (comment).

[AgustinBettati]

Hello @postatum! I was able to reproduce the error and created the following internal ticket: https://www.mulesoft.org/jira/browse/APIMF-2388
We will keep you updated on the status of the issue.

[arielmirra]

Good morning @postatum! I've been reviewing and have some comments regarding this issue, hope this helps:

1. When changing specs in resolution (e.x. OAS30 -> RAML10) the compatibility pipeline must be used in resolution
2. Although it's technically possible, we don't support conversion to RAML08 (as far as the raml08resolver doesn't support compatibility pipeline)

I've reproduced your exact case in javascript and the code is the following:

const amf = require('amf-client-js')
​
const spec = `{
  "openapi":"3.0.1",
  "info":{
    "title":"API Endpoints",
    "version":"v1"
  },
  "paths":{
    "/api/users":{
      "get":{
        "operationId":"getAllUsers",
        "parameters":[
          {
            "name":"def",
            "in":"query",
            "description":"default parameter description..",
            "required":true,
            "schema":{
              "type":"string"
            }
          }
        ]
      }
    }
  }
}
`
​
async function main () {
	await amf.AMF.init()
	const parsedModel = await new amf.Oas30Parser().parseStringAsync(spec)
	const model = await new amf.Raml10Resolver().resolve(parsedModel, 'compatibility')
	const str = await new amf.Raml10Renderer().generateString(model)
	console.log(str)
}
(async () => {main()})()

Resulting in the exact same generated API Spec in RAML1.0 that you appended:

#%RAML 1.0
title: API Endpoints
version: v1
/api/users:
  get:
    displayName: getAllUsers
    queryParameters:
      def:
        description: default parameter description..
        required: true
        type: string

I'm closing this issue as won't fix. If there are any questions I'll be following this thread or you can open a new issue with updated information if neccesary.

Thank you for reading!