Skip to content

Commit

Permalink
Auto-generate GraphQL comments in SDL to support a self-documenting A…
Browse files Browse the repository at this point in the history 
…PI (#5824)

Co-authored-by: Tobbe Lundberg <[email protected]>
Co-authored-by: Dominic Saadi <[email protected]>
  • Loading branch information
@dthyresson @Tobbe @jtoar
3 people authored Aug 4, 2022
1 parent 1d728b0 commit f699e31
Show file tree
Hide file tree
Showing 25 changed files with 1,534 additions and 93 deletions.
36 changes: 26 additions & 10 deletions __fixtures__/test-project/api/db/schema.prisma
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,32 +17,48 @@ model UserExample {
name String?
}


/// A blog post.
model Post {
/// The unique identifier of a post.
id Int @id @default(autoincrement())
/// The title of a post.
title String
/// The content of a post.
body String
/// When the post was created.
createdAt DateTime @default(now())
/// The id of the author who wrote the post.
authorId Int
/// Who authored the post.
author User @relation(fields: [authorId], references: [id])
}

model Contact {
/// The unique identifier of a contact.
id Int @id @default(autoincrement())
/// The name of the contact.
name String
/// The email of the contact.
email String
/// The message of the contact.
message String
/// When the contact was created.
createdAt DateTime @default(now())
}

/// A User.
model User {
/// The unique identifier of a user.
id Int @id @default(autoincrement())
/// The user's email address.
email String @unique
hashedPassword String
fullName String
hashedPassword String
salt String
resetToken String?
resetTokenExpiresAt DateTime?
/// Roles to which the user belongs.
roles String?
/// Posts the user has authored.
posts Post[]
}

model Contact {
id Int @id @default(autoincrement())
name String
email String
message String
createdAt DateTime @default(now())
}
29 changes: 16 additions & 13 deletions docs/docs/cli-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -897,11 +897,13 @@ A scaffold quickly creates a CRUD for a model by generating the following files
The content of the generated components is different from what you'd get by running them individually.
| Arguments & Options | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | Model to scaffold. You can also use `<path/model>` to nest files by type at the given path directory (or directories). For example, `redwood g scaffold admin/post` |
| `--force, -f` | Overwrite existing files |
| `--typescript, --ts` | Generate TypeScript files Enabled by default if we detect your project is TypeScript |
| Arguments & Options | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | Model to scaffold. You can also use `<path/model>` to nest files by type at the given path directory (or directories). For example, `redwood g scaffold admin/post` |
| `--docs` | Use or set to `true` to generated comments in SDL to use in self-documentating your app's GraphQL API. See: [Self-Documenting GraphQL API](./graphql.md#self-documenting-graphql-api) [default:false] |
| `--force, -f` | Overwrite existing files |
| `--tailwind` | Generate TailwindCSS version of scaffold.css (automatically set to `true` if TailwindCSS config exists) |
| `--typescript, --ts` | Generate TypeScript files Enabled by default if we detect your project is TypeScript |
**Usage**
Expand Down Expand Up @@ -1075,13 +1077,14 @@ The sdl will inspect your `schema.prisma` and will do its best with relations. S
<!-- See limited generator support for relations
https://community.redwoodjs.com/t/prisma-beta-2-and-redwoodjs-limited-generator-support-for-relations-with-workarounds/361 -->
| Arguments & Options | Description |
| -------------------- | ------------------------------------------------------------------------------------ |
| `model` | Model to generate the sdl for |
| `--crud` | Set to `false`, or use `--no-crud`, if you do not want to generate mutations |
| `--force, -f` | Overwrite existing files |
| `--tests` | Generate service test and scenario [default: true] |
| `--typescript, --ts` | Generate TypeScript files Enabled by default if we detect your project is TypeScript |
| Arguments & Options | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model` | Model to generate the sdl for |
| `--crud` | Set to `false`, or use `--no-crud`, if you do not want to generate mutations |
| `--docs` | Use or set to `true` to generated comments in SDL to use in self-documentating your app's GraphQL API. See: [Self-Documenting GraphQL API](./graphql.md#self-documenting-graphql-api) [default: false] |
| `--force, -f` | Overwrite existing files |
| `--tests` | Generate service test and scenario [default: true] |
| `--typescript, --ts` | Generate TypeScript files Enabled by default if we detect your project is TypeScript |
> **Note:** The generated sdl will include the `@requireAuth` directive by default to ensure queries and mutations are secure. If your app's queries and mutations are all public, you can set up a custom SDL generator template to apply `@skipAuth` (or a custom validator directive) to suit you application's needs.
Expand Down Expand Up @@ -1264,7 +1267,7 @@ Services are where Redwood puts its business logic. They can be used by your Gra
| `name` | Name of the service |
| `--force, -f` | Overwrite existing files |
| `--typescript, --ts` | Generate TypeScript files Enabled by default if we detect your project is TypeScript |
| `--tests` | Generate test and scenario files [default: true] |
| `--tests` | Generate test and scenario files [default: true] |
**Destroying**
Expand Down
Loading

0 comments on commit f699e31

Please sign in to comment.