Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/well-balanced/gql-docgen
documentation generator for GraphQL API
https://github.com/well-balanced/gql-docgen
docgen docs graphql
Last synced: 27 days ago
JSON representation
documentation generator for GraphQL API
- Host: GitHub
- URL: https://github.com/well-balanced/gql-docgen
- Owner: well-balanced
- License: mit
- Created: 2022-05-26T04:52:42.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-06-19T16:32:50.000Z (over 2 years ago)
- Last Synced: 2024-10-05T01:01:41.457Z (about 1 month ago)
- Topics: docgen, docs, graphql
- Language: TypeScript
- Homepage:
- Size: 43.9 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GraphQL Document Generator
documentation generator for GraphQL API
[![NPM Version][npm-image]][npm-url]
[npm-image]: https://img.shields.io/npm/v/gql-docgen.svg
[npm-url]: https://npmjs.org/package/gql-docgen
## Usage
the first argument receives a path to find the schema source, and second argument receives a path to export the markdown file.
```sh
$ npx gql-docgen [schema-source] [out-dir]
```
### GrahqhQL endpoint
GraphQL endpoints are also supported.
```sh
$ npx gql-docgen https://your-gql-api/graphql ./out
```
### With file system
if you want to use a local file or folder as a schema source, enter that path.
```sh
# folder
$ npx gql-docgen ./typeDefs ./out
# file
$ npx gql-docgen ./schema.gql ./out
```
### Reserved tags
the informations can be expressed by attaching a reserved tag in the docstring of the schema file.
**@req**
The `@req` tag inside the docstring is shown as a block of code in the paragraph "Request"
```graphql
type Query {
"""
@req
```graphql
query GetGuestCart($input: GetCartByGuestInput!) {
guestCart(input: $input) {
items {
_id
name
quantity
}
total
}
}
```
"""
guestCart(input: GetCartByGuestInput!): GetCartPayload!
}
```
**@res**
The `@res` tag inside the docstring is shown as a block of code in the paragraph "Response"
```graphql
type Query {
"""
@res
```json
{
"data:: {
"items": {
...
}
}
}
```
"""
guestCart(input: GetCartByGuestInput!): GetCartPayload!
}
```
**@desc**
The `@desc` tag adds a description just below the resolver name.
```graphql
type Query {
"""
@desc Gets the list of customer's cart items
"""
guestCart(input: GetCartByGuestInput!): GetCartPayload!
}
```
### Options
**headers**
when you fetch schemas from your graphql api, you might need to set your authorization key. if you attach `headers` option, you can.
```sh
$ npx gql-docgen https://your-gql-api/graphql ./out --header "Authorization=[your token]"
```
**title**
you can set heading with `title` option.
```sh
$ npx gql-docgen ./schema.graphql ./out --title Commerce
```
## License
MIT