translation-to-graphql

translation-to-graphql

The purpose of this package is the generate a GraphQL schema from a swagger file and translation file. This GraphQL schema can then be served on an express server and queried to return the appropriate results. This library is only intended to be used for the Listen Online project. This package contains a few utility functions as well for managing the swagger files and translation files.

Getting Started

Prerequisites

• nodejs

Installing

Run

yarn 

to install dependencies

Dependencies

This package uses a modified version of the openapi-to-graphql library. The main change is that it calls the endpoint defined in operationId, not the endpoint itself. That is, if an endpoint has name "/popular" and its operationId is "popular-get:/subreddits/popular", then the resolver function defined in the GraphQL schema will have the endpoint "/subreddits/popular" instead of "/popular".

The user can name the endpoints anything in the translation file (as long as there are no duplicates). Those endpoints names get transferred to the generated swagger file, but the underlying endpoint name still has to be saved in the operationId.

For example, the swagger and translation file could look like

let swaggerFile = {
    ...
};

let translationFile = {
    "endpoints": {
        "/subreddits/popular": {
            "popular1": {
                "get": {
                    ...
                }
            },
            "popular2" : {
                "get": {
                    ...
                }
            }
        }
        "/subreddits/hot" : {
            "hot" : {
                "get": {
                    ...
                }
            }
        }
    }
};

After generating the new swagger file, it would look like:

let newSwagger = {
    "paths": {
        "/popular1": {
            "get": {
                "opeartionId": "popular1-get:/subreddits/popular"
            },
            ...
        },
        "/popular2" : {
            "get": {
                "opeartionId": "popular2-get:/subreddits/popular"
            },
            ...
        },
        "/hot" : {
            "get": {
                "opeartionId": "hot-get:/subreddits/hot"
            },
            ...
        }
    }
}

The openapi-to-graphql library normally reads the endpoint names (e.g. /popular1, /popular2, and /hot), but those endpoints are user defined from the translation tool so they do not exist. The modified openapi-to-graphql reads the endpoints from the opeartionIDs (e.g. /subreddits/popular and /subreddits/hot) and those become the URLs in the resolver functions. This is what we want since those endpoints come from the swagger files so they actually exist. That is, the swagger files contain endpoints from the reddit APIs so they define the APIs. The endpoint names defined in the translation file from the translation tool are user-defined.

The modified library code repository is here: https://github.com/wangleex/openapi-to-graphql

Deployment

1. Update package.json with new version number
2. Run npm publish

Documentation

This package uses jsDoc for documentation. The documentation HTML file can be found here: index.html

Just open up the index.html and it will bring up the auto generated documentation in the web browser.