Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chirino/graphql-4-apis
Lets you create a GraphQL gateway services for your openapi documented API services.
https://github.com/chirino/graphql-4-apis
go golang graphql openapi swagger
Last synced: about 2 months ago
JSON representation
Lets you create a GraphQL gateway services for your openapi documented API services.
- Host: GitHub
- URL: https://github.com/chirino/graphql-4-apis
- Owner: chirino
- License: bsd-2-clause
- Created: 2020-01-28T23:59:39.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-07-08T18:38:36.000Z (about 3 years ago)
- Last Synced: 2024-06-21T04:47:24.436Z (3 months ago)
- Topics: go, golang, graphql, openapi, swagger
- Language: Go
- Homepage: https://github.com/chirino/graphql-4-apis
- Size: 1.62 MB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GraphQL-4-APIs
Lets you create a [GraphQL](https://graphql.org/) gateway service for your
[OpenAPI Specifications (OAS)](https://github.com/OAI/OpenAPI-Specification)
or [Swagger](https://swagger.io/specification/v2/) documented API services. This lets you execute
GraphQL queries/mutations against your APIs.
## Getting started
### CLI
The Command Line Interface (CLI) provides a convenient way to start a GraphQL server wrapping an API for a given OpenAPI Specification:
1. Install the `graphql-4-apis` CLI using:
```bash
go get -u github.com/chirino/graphql-4-apis
```
2. Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:
```bash
$ graphql-4-apis api myopenapi.json
GraphQL service running at http://localhost:8080/graphql
GraphiQL UI running at http://localhost:8080/graphiql
```
## Characteristics
- **Queries**
Defined headers, query, and path open api parameters become type checked parameters to the GraphQL queries. Responses
get automatically generated graphql types.
- **Mutations**
Non-safe, non-idempotent API operations are translated to GraphQL [mutations](http://graphql.org/learn/queries/#mutations).
GraphQL Input Objects schemas are generated for the input body so that that input data is type checked.
- **Authentication**
All HTTP headers on the GraphQL request are passed through to the upstream API.
A login mutation is provided so that allows you to store a
bearer token in an http cookie that is used in subsequent request to populate the Authorization header
on API requests. This comes in handy if your using the GraphiQL interface since you can't
easily set Authorization headers using that interface. A logout mutation is also available to
clear the cookie.
- **API Sanitation**
API names not compatible with GraphQL are automatically sanitized. For example, API parameters and data definition names with unsupported
characters (e.g., `-`, `.`, `,`, `:`, `;`...) are replaced with `_`.
- **Swagger and OpenAPI 3 support** OpenAPI-to-GraphQL can handle both Swagger (OpenAPI specification 2.0) as well as OpenAPI specification 3.
- **Support for json objects with dynamic keys** GraphQL object types requires all fields of a type to be known, openapi
allows json types with dynamic object keys. In these cases, we map the object type to an array of key value pairs `[ResultProp!]`
that using this template:
```graphql
type ResultProp {
key String!
value
}
```
## License
[BSD](./LICENSE)
## Development
* We love [pull requests](https://github.com/chirino/graphql-4-apis/pulls)
* Is one of your APIs not working well with this project? [Lets us know](https://github.com/chirino/graphql-4-apis/issues)
* GraphQL-4-APIs is written in [Go](https://golang.org/). It should work on any platform where go is supported.
* Built on this [GraphQL](https://github.com/chirino/graphql) framework
* Currently focused on being a CLI based server, but eventually would like to provided library to allow it to be used
in your custom GraphQL servers
## Future Work
* make operation id's optional
* use links in the openapi v3 spec to resolve relationships in the the graph structure
* support passing custom headers and query parameters to api calls
* support subscriptions
* allow customizing the generated GraphQL schema
* https secured graphql endpoints
* sanitization on json schema field names.
* setup ci jobs and have some binary releases
## Similar projects
- [openapi-to-graphql](https://github.com/IBM/openapi-to-graphql) Very similar to this project, written in javascript
- [swagger-to-graphql](https://github.com/yarax/swagger-to-graphql) turns a given Swagger (OpenAPI Specification 2.0) into a GraphQL interface, which resolves against the original API. GraphQL schema is based on endpoints, not on data definitions. No links are considered.
- [json-to-graphql](https://github.com/aweary/json-to-graphql) turns given JSON objects / arrays into a GraphQL schema. `resolve` functions need to be provided by the user.
- [StackOverflow discussion](https://stackoverflow.com/questions/38339442/json-schema-to-graphql-schema-converters) points to the above projects.