Search code examples
swaggeropenapihighlight.js

How to convert OpenAPI response example content to simple JSON ready for code highlighter?


I want to display example content of a response in paths.{url}.{method}.responses section of OpenAPI v3.0.0 specs in highlight.js. I am currently getting such object from a remote JSON OpenAPI spec:

"responses": {
    "200": {
        "content": {
            "application/json": {
                "schema": {
                    "properties": {
                        "data": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/AdminApi-AdminResource"
                            }
                        },
                        "meta": {
                            $ref: "#/components/schemas/PaginationMeta"
                        }
                    },
                    "type": "object"
                }
            }
        }
    }
}

#/components/schemas/AdminApi-AdminResource:

{
    "title": "Admin api admin resource",
    "description": "Admin api admin resource",
    "properties": {
        "id": {
            "type": "integer",
            "example": 1
        },
        "email": {
            "type": "string",
            "example": "[email protected]"
        },
        "created_at": {
            "type": "string",
            "example": "2022-10-17T13:55:59.000000Z"
        },
        "updated_at": {
            "type": "string",
            "example": "2022-10-17T13:55:59.000000Z"
        }
    },
    "type": "object"
}

#/components/schemas/PaginationMeta:

{
    "properties": {
        "current_page": {
            "type": "number",
            "example": 1
        },
        "from": {
            "type": "number",
            "example": 1
        },
        "last_page": {
            "type": "number",
            "example": 1
        },
        "per_page": {
            "type": "number",
            "example": 100
        },
        "to": {
            "type": "number",
            "example": 1
        },
        "total": {
            "type": "number",
            "example": 1
        }
    },
    "type": "object"
}

What I need is to parse/convert these response objects from OpenAPI to simple JS/JSON objects:

{
    "data": {
        "items": [
            {
                "id": 1,
                "email": "[email protected]",
                "created_at": "2022-10-17T13:55:59.000000Z",
                "updated_at": "2022-10-17T13:55:59.000000Z"
            }
        ]
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 100,
        "to": 1,
        "total": 1
    }
}

And display these simple objects in code highlighter, for example, highlight.js.

I have no idea how to solve this problem or in what direction should I start searching this problem.


Solution

  • After several hours of searching, I've found two useful packages that can help to achieve the goals described in the question above.

    • @apidevtools/swagger-parser - to parse OpenAPI spec and replace $ref with the corresponding value from spec components.
    • openapi-sampler - to generate samples based on OpenAPI payload/response schema to display it in code highlighter.
    import SwaggerParser from '@apidevtools/swagger-parser';
    
    // To replace $ref with corresponding value from spec
    const dereferencedData = await SwaggerParser.dereference(data);
    
    import { sample } from 'openapi-sampler';
    
    /**
     * someEndpointName - is an endpoint name (for example, /test/get/user)
     * httpMethod - get, post, etc.
     * httpStatus - 200, 400, 500, etc.
     * contentType - for example, application/json
     */
    const schema = dereferencedData[someEndpointName][httpMethod].responses[httpStatus].content[contentType].schema;
    
    // Simple code in the specified content type
    const responseSample = sample(schema);