From 00029edabf95ab06ef54cca111a170ce4f20c57e Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Wed, 2 Oct 2024 13:48:50 -0700 Subject: [PATCH] feat: add example folder (#14) --- README.md | 22 +++- example/README.md | 7 ++ example/config-schema.json | 203 +++++++++++++++++++++++++++++++++++++ example/config-schema.sh | 1 + example/config.yml | 18 ++++ example/start.sh | 4 + 6 files changed, 250 insertions(+), 5 deletions(-) create mode 100644 example/README.md create mode 100644 example/config-schema.json create mode 100644 example/config-schema.sh create mode 100644 example/config.yml create mode 100755 example/start.sh diff --git a/README.md b/README.md index 8c818a4..6dd7696 100644 --- a/README.md +++ b/README.md @@ -20,22 +20,34 @@ You can run this project as a [Docker image](https://github.com/apollosolutions/ Here's how to use the pre-built Docker image, mounting a local `config.yml` to a container and using it as a configuration: ``` -docker run -p 8080:8080 --mount "type=bind,source=./config.yml,target=/app/config.yml" ghcr.io/apollosolutions/persisted-query-to-rest:v0.1.1 --config /app/config.yml +docker run -p 8080:8080 --mount "type=bind,source=./config.yml,target=/app/config.yml" ghcr.io/apollosolutions/persisted-query-to-rest:latest --config /app/config.yml ``` ## Usage -There are two flags for `persisted-query-to-rest`: +There is one flag for `persisted-query-to-rest`: * `--config`, which specifies the config location -* `--config-schema` which forces the application to print out a JSON schema for YAML validation - * See [example_config.yaml](./example_config.yaml) to see an example of setting it up - * We use [Red Hat's YAML extension for VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) to validate ## Configuration See [`example_config.yaml`](./example_config.yaml) for a complete example of a configuration. +### Generate a configuration schema +To generate a YAML schema file you can run the binary with the command `config-schema`. This file can then be configured in your config YAML file to provide autocomplete and validation of the YAML file right in your IDE + +```shell +# forces the application to print out a JSON schema for YAML validation +./persisted-query-to-rest config-schema > config-schema.json +``` +OR +```shell +docker run ghcr.io/apollosolutions/persisted-query-to-rest:latest config-schema > config-schema.json +``` + +* See [example_config.yaml](./example_config.yaml) to see an example of setting it up +* We use [Red Hat's YAML extension for VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) to validate + ### Common This configuration contains the general configuration settings for `persisted-query-to-rest`. diff --git a/example/README.md b/example/README.md new file mode 100644 index 0000000..2e336a6 --- /dev/null +++ b/example/README.md @@ -0,0 +1,7 @@ +# Example + +This small example starts up using the `latest` docker image. Feel free to edit the config locally and try for yourself. + +* Run `./config-schema.sh` to generate a new config json file to help with YAML autocomplete +* Run `./start.sh` to quickly run the latest image with all the config files in the local folder + diff --git a/example/config-schema.json b/example/config-schema.json new file mode 100644 index 0000000..0721768 --- /dev/null +++ b/example/config-schema.json @@ -0,0 +1,203 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Config", + "type": "object", + "required": [ + "common", + "endpoints" + ], + "properties": { + "common": { + "description": "The common configuration for the server", + "allOf": [ + { + "$ref": "#/definitions/ServerConfig" + } + ] + }, + "endpoints": { + "description": "The list of endpoints that the server should expose", + "type": "array", + "items": { + "$ref": "#/definitions/Endpoint" + } + } + }, + "definitions": { + "Endpoint": { + "type": "object", + "required": [ + "path", + "pq_id" + ], + "properties": { + "body_params": { + "description": "The body parameters that the endpoint should accept", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/definitions/Parameter" + } + }, + "method": { + "description": "The method that the endpoint should accept", + "default": "GET", + "allOf": [ + { + "$ref": "#/definitions/HttpMethod" + } + ] + }, + "path": { + "description": "The path that the endpoint should be exposed on", + "type": "string" + }, + "path_arguments": { + "description": "The path arguments that the endpoint should accept", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/definitions/Parameter" + } + }, + "pq_id": { + "description": "The persisted query ID that the endpoint should use", + "type": "string" + }, + "query_params": { + "description": "The query parameters that the endpoint should accept", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/definitions/Parameter" + } + } + } + }, + "HttpMethod": { + "description": "The HTTP method for the endpoint to accept", + "type": "string", + "enum": [ + "GET", + "POST", + "PUT", + "PATCH", + "DELETE" + ] + }, + "LogLevel": { + "description": "The log level that the server should use", + "type": "string", + "enum": [ + "trace", + "debug", + "info", + "warn", + "error" + ] + }, + "Logging": { + "type": "object", + "properties": { + "format": { + "description": "The format that the logs should be output in", + "default": "pretty", + "type": "string" + }, + "level": { + "description": "The log level that the server should use", + "default": "info", + "allOf": [ + { + "$ref": "#/definitions/LogLevel" + } + ] + } + } + }, + "ParamKind": { + "description": "The kind of parameter that is expected if it is not a string", + "type": "string", + "enum": [ + "int", + "string", + "float", + "object", + "array", + "boolean" + ] + }, + "Parameter": { + "type": "object", + "required": [ + "from" + ], + "properties": { + "from": { + "description": "The parameter name that the user will use; e.g. `id` in `/user/:id` or /user/?id=1234", + "type": "string" + }, + "kind": { + "description": "The kind of parameter that is expected if it is not a string", + "default": "string", + "allOf": [ + { + "$ref": "#/definitions/ParamKind" + } + ] + }, + "required": { + "description": "Whether the parameter is required or not; by default it is false", + "default": false, + "type": "boolean" + }, + "to": { + "description": "If the operation uses a different name, this is the name the variable should be renamed to", + "type": [ + "string", + "null" + ] + } + } + }, + "ServerConfig": { + "type": "object", + "required": [ + "graphql_endpoint" + ], + "properties": { + "graphql_endpoint": { + "description": "The GraphQL endpoint the server will forward requests to", + "type": "string" + }, + "listen": { + "description": "The address that the server should listen on", + "default": "127.0.0.1:4000", + "type": "string" + }, + "logging": { + "description": "Basic logging configuration", + "anyOf": [ + { + "$ref": "#/definitions/Logging" + }, + { + "type": "null" + } + ] + }, + "path_prefix": { + "description": "The prefix for the endpoints the server should use; defaults to `/api/v1`", + "default": "/api/v1", + "type": "string" + } + } + } + } +} diff --git a/example/config-schema.sh b/example/config-schema.sh new file mode 100644 index 0000000..ed04339 --- /dev/null +++ b/example/config-schema.sh @@ -0,0 +1 @@ +docker run ghcr.io/apollosolutions/persisted-query-to-rest:latest config-schema > config-schema.json diff --git a/example/config.yml b/example/config.yml new file mode 100644 index 0000000..70d709c --- /dev/null +++ b/example/config.yml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=config-schema.json +# Common config for all endpoints +common: + path_prefix: "/api/v1" + listen: "0.0.0.0:3000" + graphql_endpoint: "https://localhost:3000/" + logging: + level: info + +# A list of all the new endpoints to create +endpoints: + # Create an endpoint that requires the id in the path + - path: "/users/:id" + pq_id: "123456789" + path_arguments: + # Map the arguments to the GraphQL arg called $userId + - from: "id" + to: "userId" diff --git a/example/start.sh b/example/start.sh new file mode 100755 index 0000000..8d76eba --- /dev/null +++ b/example/start.sh @@ -0,0 +1,4 @@ +docker run \ + -it -p 8080:8080 \ + --mount "type=bind,source=./config.yml,target=/app/config.yml" \ + ghcr.io/apollosolutions/persisted-query-to-rest:latest --config /app/config.yml