How can I show an array of objects? about openapi-comment-parser

[andyslack]

Thanks @bourdakos1

I will push my code up so you can see the JSON and the docs, if thats not enough I will get you access to the github repo :)

Thank you so much for your quick replies. It is an awesome program

[bourdakos1]

Also, if you’re not comfortable with yaml, json is technically valid yaml so you could change this to json syntax (but keep the .yaml extension) or do a mix of both:

WebhookExample:
    value: [
        {
            webhook_id: 1
            app_id: 1
            url: https://example.com
            resources: ["post","like"]
            created_at: 2000-01-01 00:00:00
            updated_at: 2000-01-01 00:00:00
        }
    ]

[andyslack]

Amazing!! Thank you so much!!

[bourdakos1]

I’m not sure what your code looks like, but if you have a User schema you should be able to do something like this:

/**
 * GET /users
 * @summary Returns a list of users.
 * @response 200 - array of users
 * @responseContent {User[]} 200.application/json
 */

[andyslack]

Hi @bourdakos1

Thank you, it's not working for me. Here is the code for my webhook GET endpoints:

    /**
     * GET /webhook/{webhook_id}
     * @queryParam {string} app_id - Your application ID
     * @queryParam {string} app_api_key - Your application API Key
     * @queryParam {string} admin_api_key - Your applications admin API Key
     * @tag Webhook
     * @summary Get Webhook
     * @description Get a specific item
     * @response 200 - OK
     * @responseContent {Webhook} 200.application/json
     * @responseExample {WebhookExample} 200.application/json.WebhookExample
     * @response 400 - Bad request - Check you are passing all the required params
     * @response 401 - Authorization
     * @response 404 - Not Found - No items available
     * @response 500 - Unexpected error.
     */

    /**
     * GET /webhooks
     * @queryParam {string} app_id - Your application ID
     * @queryParam {string} app_api_key - Your application API Key
     * @queryParam {string} admin_api_key - Your applications admin API Key
     * @queryParam {integer} [offset=0] - The number of items to skip before starting to collect the result set.
     * @queryParam {integer} [limit=20] - The number of items to return.
     * @queryParam {integer} [after] - Get results after a specific item id
     * @queryParam {date-time} [from] - Get results after a specific datetime
     * @queryParam {date-time} [to] - Get results before a specific datetime
     * @tag Webhook
     * @summary Get Webhooks
     * @description Get an array of items
     * @response 200 - OK
     * @responseContent {Webhook[]} 200.application/json
     * @responseExample {WebhookExample} 200.application/json.WebhookExample
     * @response 400 - Bad request - Check you are passing all the required params
     * @response 401 - Authorization
     * @response 404 - Not Found - No items available
     * @response 500 - Unexpected error.
     */

I'm using Redoc to pretty print the OpenAPI file to screen and its not showing the array but just the object.

[bourdakos1]

That looks good to me, can you show what Webhook schema looks like and what the generated json is? Or create a repo with the minimum reproducible issue so I can test it out

[bourdakos1]

Oh wait maybe I never implemented this... It looks like I use a workaround by creating a schema ArrayOfUsers lol 😬

https://github.com/bee-travels/openapi-comment-parser/blob/master/docs/describing-responses.md

[bourdakos1]

I’ll try and push a fix for this if it’s the case

[bourdakos1]

oh nevermind this should definitely work. We have an example:

openapi-comment-parser/example/src/routes/pet.js

Line 63 in b947a4c

* @responseContent {Pet[]} 200.application/json

and it seems to generate the proper openapi json

[andyslack]

Hi @bourdakos1

https://api.juicyllama.com/docs/openapi.json - JSON

https://api.juicyllama.com/ - Redoc

Let me know if you need access to the codebase.

[bourdakos1]

oh, Webhook[] is an array, but the example you have is WebhookExample which is not an array:

[andyslack]

Sorry @bourdakos1

How in YAML would I denote an example as an array?

Here is my WebhookExample

WebhookExample:
      value:
        webhook_id: 1
        app_id: 1
        url: https://example.com
        resources: ["post","like"]
        created_at: 2000-01-01 00:00:00
        updated_at: 2000-01-01 00:00:00

How can I turn this into an array and setup for example WebhooksExample

Even better, is there a way to reference the WebhookExample in the WebhooksExample so I dont need to duplicate code?

[bourdakos1]

This part isn’t specific to the comment parser, you should be able to find more info from the open api spec: https://swagger.io/specification/

For arrays in yaml you should just have to add a dash in front of webhook id:

WebhookExample:
    value:
      - webhook_id: 1
        app_id: 1
        url: https://example.com
        resources: ["post","like"]
        created_at: 2000-01-01 00:00:00
        updated_at: 2000-01-01 00:00:00