https://github.com/udamir/graphapi
The GraphAPI Specification Repository. "OpenApi" for GraphQL
https://github.com/udamir/graphapi
Last synced: 3 months ago
JSON representation
The GraphAPI Specification Repository. "OpenApi" for GraphQL
- Host: GitHub
- URL: https://github.com/udamir/graphapi
- Owner: udamir
- License: mit
- Created: 2023-03-04T21:12:44.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-28T10:02:36.000Z (over 2 years ago)
- Last Synced: 2025-04-03T10:41:59.092Z (9 months ago)
- Language: TypeScript
- Homepage:
- Size: 306 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GraphAPI
This package provides utils to convert GraphQL schema into GraphAPI document and back - [online demo](https://udamir.github.io/graphapi/)
The GraphAPI Specification is GraphQL introspection alternative, but based on JsonSchema - OpenApi for GraphQL
## Features
- JsonSchema based GraphQL document, similar to OpenApi
- Support custom directives in schema (meta)
- GraphAPI document can be build from GraphQL Schema or Introspection
- GraphAPI document can be converted to GraphQL Schema
- Typescript syntax support out of the box
- No dependencies, can be used in nodejs or browser
## Installation
```SH
npm install gqlapi --save
```
## Usage
### Build GraphAPI document from Schema or Introspection
```ts
import { buildSchema, graphqlSync, getIntrospectionQuery } from "graphql"
import { buildFromSchema, buildFromIntrospection } from 'gqlapi'
// build from GraphQL schema
const schema = buildSchema(data)
const graphapi = buildFromSchema(schema)
// build from GraphQL introspection
const introspection = graphqlSync(data, getIntrospectionQuery()).data
const graphapi = buildFromIntrospection(introspection)
```
> Important: only deprecated directives will be in result, as introspection not support custom directives meta
### Print GraphQL schema document from GraphAPI document
```ts
import { printSchema } from 'gqlapi'
const schema = printSchema(graphapi)
console.log(schema)
```
## Example
### Input data:
```graphql
type Todo {
id: ID!
name: String!
completed: Boolean
color: Color
"A field that requires an argument"
colors(filter: [Color!]!): [Color!]!
}
enum Color {
"Red color"
RED
"Green color"
GREEN
}
input TodoInputType {
name: String!
completed: Boolean @deprecated(reason: "not used")
color: Color = RED
}
type Query {
"A Query with 1 required argument and 1 optional argument"
todo(
id: ID!
"A default value of false"
isCompleted: Boolean = false
): Todo
""" Returns a list (or null) that can contain null values """
todos(
"Required argument that is a list that cannot contain null values"
ids: [String!]!
): [Todo]
}
type Mutation {
"A Mutation with 1 required argument"
create_todo(
todo: TodoInputType!
): Todo!
}
```
### Output result in yaml format:
```yaml
graphapi: 0.1.2
queries:
todo:
description: A Query with 1 required argument and 1 optional argument
args:
type: object
required:
- id
properties:
id:
type: string
format: ID
isCompleted:
type: boolean
description: A default value of false
default: false
$ref: '#/components/objects/Todo'
nullable: true
todos:
description: Returns a list (or null) that can contain null values
args:
type: object
required:
- ids
properties:
ids:
type: array
items:
type: string
description: Required argument that is a list that cannot contain null values
type: array
items:
$ref: '#/components/objects/Todo'
nullable: true
nullable: true
mutations:
create_todo:
description: A Mutation with 1 required argument
args:
type: object
required:
- todo
properties:
todo:
$ref: '#/components/inputObjects/TodoInputType'
$ref: '#/components/objects/Todo'
components:
objects:
Todo:
title: Todo
type: object
required:
- id
- name
- colors
properties:
id:
type: string
format: ID
name:
type: string
completed:
type: boolean
color:
$ref: '#/components/enums/Color'
colors:
description: A field that requires an argument
type: array
items:
$ref: '#/components/enums/Color'
args:
type: object
required:
- filter
properties:
filter:
type: array
items:
$ref: '#/components/enums/Color'
enums:
Color:
title: Color
type: string
values:
- value: RED
description: Red color
- value: GREEN
description: Green color
inputObjects:
TodoInputType:
title: TodoInputType
type: object
required:
- name
properties:
name:
type: string
completed:
deprecated:
reason: not used
type: boolean
color:
$ref: '#/components/enums/Color'
default: RED
directives:
include:
title: include
description: >-
Directs the executor to include this field or fragment only when the
`if` argument is true.
locations:
- FIELD
- FRAGMENT_SPREAD
- INLINE_FRAGMENT
args:
type: object
required:
- if
properties:
if:
type: boolean
description: Included when true.
repeatable: false
skip:
title: skip
description: >-
Directs the executor to skip this field or fragment when the `if`
argument is true.
locations:
- FIELD
- FRAGMENT_SPREAD
- INLINE_FRAGMENT
args:
type: object
required:
- if
properties:
if:
type: boolean
description: Skipped when true.
repeatable: false
```
## Documentation
TBD
## Contributing
When contributing, keep in mind that it is an objective of `graphapi` to have no package dependencies. This may change in the future, but for now, no-dependencies.
Please run the unit tests before submitting your PR: `npm test`. Hopefully your PR includes additional unit tests to illustrate your change/modification!
## License
MIT