Skip to content

Commit d6dd6c4

Browse files
lacatoirelacatoire
authored
Improve create-client documentation (#2264)
1 parent e3b3c8c commit d6dd6c4

File tree

11 files changed

+75
-3
lines changed

11 files changed

+75
-3
lines changed

‎create-client/custom.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,7 @@ fn main() {
125125
];
126126
}
127127
```
128+
129+
## Troubleshooting
130+
131+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/index.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,26 @@ It is able to generate apps using the following frontend stacks:
2121
Create Client works especially well with APIs built with the
2222
[API Platform](https://api-platform.com) framework.
2323

24+
## Usage
25+
26+
```console
27+
npm init @api-platform/client entrypoint outputDirectory
28+
```
29+
30+
You can run `npm init @api-platform/client -- --help` to see all available options:
31+
32+
| Option | Description |
33+
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
34+
| `-r, --resource [resourceName]` | Generate CRUD for the given resource only |
35+
| `-g, --generator [generator]` | Generator to use: `next`, `nuxt`, `quasar`, `react`, `react-native`, `typescript`, `vue`, `vuetify`, or a path to a [custom generator](custom.md) |
36+
| `-f, --format [hydra\|openapi3\|openapi2]` | API documentation format (default: `hydra`) |
37+
| `-t, --template-directory [templateDirectory]` | Custom templates directory |
38+
| `-p, --hydra-prefix [hydraPrefix]` | The Hydra prefix used by the API |
39+
| `--bearer [bearer]` | Token for bearer auth (Hydra only) |
40+
| `--username [username]` | Username for basic auth (Hydra only) |
41+
| `--password [password]` | Password for basic auth (Hydra only) |
42+
| `-s, --server-path [serverPath]` | Path to Express server file for dynamic route addition (Next.js only) |
43+
2444
## Features
2545

2646
- Generates high-quality TypeScript:

‎create-client/nextjs.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,3 +145,7 @@ If you want to generate a production build locally with docker compose, follow
145145

146146
![List](images/nextjs/create-client-nextjs-list.png)
147147
![Show](images/nextjs/create-client-nextjs-show.png)
148+
149+
## Troubleshooting
150+
151+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/nuxt.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,3 +100,7 @@ Go to `https://localhost:3000/books/` to start using your app.
100100
## Screenshots
101101

102102
![List](images/nuxt/create-client-nuxt-list.png) ![Edit](images/nuxt/create-client-nuxt-edit.png)
103+
104+
## Troubleshooting
105+
106+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/quasar.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,3 +79,7 @@ quasar dev
7979
Go to `http://localhost:9000/books/` to start using your app.
8080

8181
**Note:** In order to Mercure to work with the demo, you have to use the port 3000.
82+
83+
## Troubleshooting
84+
85+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/react-native.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,3 +117,7 @@ expo start
117117
![Show](images/react-native/create-client-react-native-show.png)
118118
![Add](images/react-native/create-client-react-native-add.png)
119119
![Delete](images/react-native/create-client-react-native-delete.png)
120+
121+
## Troubleshooting
122+
123+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/react.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,7 @@ Go to `https://localhost/books/` to start using your app.
9090
![Show](images/react/create-client-react-show.png)
9191
![Edit](images/react/create-client-react-edit.png)
9292
![Delete](images/react/create-client-react-delete.png)
93+
94+
## Troubleshooting
95+
96+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/troubleshooting.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Troubleshooting
22

3+
> [!TIP]
4+
>
5+
> Run `npm init @api-platform/client -- --help` to see all available options.
6+
37
## Self-Signed TLS Certificate
48

59
If you are running API Platform on development machine which does not have valid TLS certificate,
@@ -11,16 +15,28 @@ NODE_TLS_REJECT_UNAUTHORIZED=0 npm init @api-platform/client --generator typescr
1115

1216
## Authenticated API
1317

14-
The generator does not perform any authentication, so you must ensure that all referenced Hydra
15-
paths for your API are accessible anonymously. If you are using API Platform this will at least
16-
include:
18+
The generator needs to access the API documentation to introspect your resources. If your API
19+
requires authentication, you can use the built-in authentication options (Hydra format only):
20+
21+
```console
22+
# Bearer token authentication
23+
npm init @api-platform/client -- --bearer "your-token" https://localhost/api src/
24+
25+
# Basic authentication
26+
npm init @api-platform/client -- --username "admin" --password "secret" https://localhost/api src/
27+
```
28+
29+
If you do not use these options, you must ensure that all referenced Hydra paths for your API are
30+
accessible anonymously. If you are using API Platform, this includes at least:
1731

1832
```console
1933
api_entrypoint ANY ANY ANY /{index}.{_format}
2034
api_doc ANY ANY ANY /docs.{_format}
2135
api_jsonld_context ANY ANY ANY /contexts/{shortName}.{_format}
2236
```
2337

38+
See [Symfony Security](../core/security.md) for details on how to configure access control rules.
39+
2440
## ApiDocumentation doesn't exist
2541

2642
If you receive `Error: The class http://www.w3.org/ns/hydra/core#ApiDocumentation doesn't exist.`

‎create-client/typescript.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,7 @@ You will obtain 2 `.ts` files arranged as following:
3535
- interfaces/
3636
- foo.ts
3737
- bar.ts
38+
39+
## Troubleshooting
40+
41+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

‎create-client/vuejs.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,3 +77,7 @@ npm run dev
7777
Go to `http://localhost:5173/books/` to start using your app.
7878

7979
**Note:** In order to Mercure to work with the demo, you have to use the port 3000.
80+
81+
## Troubleshooting
82+
83+
Having issues? Check the [Troubleshooting](troubleshooting.md) page.

0 commit comments

Comments
 (0)