diff --git a/admin/getting-started.md b/admin/getting-started.md index 4c22c8f7b7a..c39e94722b5 100644 --- a/admin/getting-started.md +++ b/admin/getting-started.md @@ -4,24 +4,19 @@ If you use the [API Platform Distribution](../distribution/), API Platform Admin is already installed, you can skip this installation guide. -Otherwise, all you need to install API Platform Admin is a JavaScript package manager. We recommend [Yarn](https://yarnpkg.com/) ([npm](https://www.npmjs.com/) is also supported). +Otherwise, follow this guide. If you don't have an existing React Application, create one using [Create React App](https://create-react-app.dev/): ```console -yarn create react-app my-admin -``` - -Go to the directory of your project: - -```console +npm init react-app my-admin cd my-admin ``` -Finally, install the `@api-platform/admin` library: +Then, install the `@api-platform/admin` library: ```console -yarn add @api-platform/admin +npm install @api-platform/admin ``` ## Creating the Admin @@ -69,6 +64,6 @@ docker compose exec php \ bin/console cache:clear --env=prod ``` -Your new administration interface is ready! Type `yarn start` to try it! +Your new administration interface is ready! Type `npm start` to try it! Note: if you don't want to hardcode the API URL, you can [use an environment variable](https://create-react-app.dev/docs/adding-custom-environment-variables). diff --git a/client-generator/nextjs.md b/client-generator/nextjs.md deleted file mode 100644 index c3b360fa009..00000000000 --- a/client-generator/nextjs.md +++ /dev/null @@ -1,64 +0,0 @@ -# Next.js Generator - -![List screenshot](images/nextjs/client-generator-nextjs-list.png) - -The Next.js Client Generator generates components for Server Side Rendered applications using [Next.js](https://nextjs.org/). - -## Install - -The easiest way to get started is to install [the API Platform distribution](../distribution/index.md). -It contains the Client Generator, all dependencies it needs, a Next.js skeleton generated with Create Next App, -a development Docker container to serve the webapp, and all the API Platform components you may need, including an API server -supporting Hydra. - -If you use API Platform, jump to the next section! - -Alternatively, create a Next.js application by executing: - -```console -npx create-next-app --typescript your-app-name -# or -yarn create next-app --typescript your-app-name -``` - -Install the required dependencies: - -```console -yarn add isomorphic-unfetch formik react-query -``` - -## Generating Routes - -If you use the API Platform distribution, generating all the code you need for a given resource is as simple as running the following command: - -```console -docker compose exec client \ - generate-api-platform-client --resource book -g next -``` - -Omit the resource flag to generate files for all resource types exposed by the API. - -If you don't use the standalone installation, run the following command instead: - -```console -npx @api-platform/client-generator https://demo.api-platform.com . --generator next --resource book -# Replace the URL by the entrypoint of your Hydra-enabled API. -# You can also use an OpenAPI documentation with `-f openapi3`. -``` - -The code has been generated, and is ready to be executed! - -## Starting the Project - -You can launch the server with - -```console -yarn dev -``` - -Go to `http://localhost:3000/books/` to start using your app. - -## Screenshots - -![List](images/nextjs/client-generator-nextjs-list.png) -![Show](images/nextjs/client-generator-nextjs-show.png) diff --git a/core/angularjs-integration.md b/core/angularjs-integration.md index 03ffa385872..b9e0ad0489a 100644 --- a/core/angularjs-integration.md +++ b/core/angularjs-integration.md @@ -1,6 +1,6 @@ # AngularJS Integration -Warning: for a new project, you should consider using [the API Platform's Progressive Web App generator](../client-generator/index.md) +Warning: for a new project, you should consider using [the API Platform's Progressive Web App generator](../create-client/index.md) (that supports React and Vue.js) instead of this Angular v1 integration. ## Restangular diff --git a/core/deprecations.md b/core/deprecations.md index c16d2f55f6e..a2b06f35afd 100644 --- a/core/deprecations.md +++ b/core/deprecations.md @@ -36,8 +36,8 @@ class Parchment As you can see, to deprecate a resource, we just have to explain what the client should do to upgrade in the dedicated attribute. The deprecation will automatically be taken into account by clients supporting the previously mentioned format, including -[API Platform Admin](../admin/index.md), [API Platform Client Generator](../client-generator/index.md) and the lower level -[api-doc-parser library](https://github.com/api-platform/api-doc-parser). +[Admin](../admin/index.md), clients created with [Create Client](../create-client/index.md) and the lower level +[api-doc-parser](https://github.com/api-platform/api-doc-parser) library. Here is how it renders for OpenAPI in the built-in Swagger UI shipped with the framework: diff --git a/core/mercure.md b/core/mercure.md index 7e650aa4cbd..c6800ca5286 100644 --- a/core/mercure.md +++ b/core/mercure.md @@ -46,9 +46,9 @@ This header allows smart clients to automatically discover the Mercure hub. ![Mercure subscriptions](images/mercure-discovery.png) -Clients generated using [the API Platform Client Generator](../client-generator/index.md) will use this capability to automatically subscribe to Mercure updates when available: +Clients generated using [Create Client](../create-client/index.md) will use this capability to automatically subscribe to Mercure updates when available: -![Screencast](../client-generator/images/client-generator-demo.gif) +![Screencast](../create-client/images/create-client-demo.gif) [Learn how to use the discovery capabilities of Mercure in your own clients](https://mercure.rocks/docs/ecosystem/awesome). diff --git a/client-generator/custom.md b/create-client/custom.md similarity index 68% rename from client-generator/custom.md rename to create-client/custom.md index 74ecb349257..007472cc371 100644 --- a/client-generator/custom.md +++ b/create-client/custom.md @@ -1,20 +1,20 @@ # Custom Generator -Client Generator provides support for many of the popular JS frameworks, but you may be using another framework or language and may need a solution adapted to your specific needs. For this cenario, you can write your own generator and pass it to the CLI using a path as the `-g` argument. +Create Client provides support for many of the popular JS frameworks, but you may be using another framework or language and may need a solution adapted to your specific needs. For this cenario, you can write your own generator and pass it to the CLI using a path as the `-g` argument. -You will probably want to extend or, at least, take a look at [BaseGenerator.js](https://github.com/api-platform/client-generator/blob/main/src/generators/BaseGenerator.js), since the library expects some methods to be available, as well as one of the [included generators](https://github.com/api-platform/client-generator/blob/main/src/generators/BaseGenerator.j) to make your own. +You will probably want to extend or, at least, take a look at [BaseGenerator.js](https://github.com/api-platform/create-client/blob/main/src/generators/BaseGenerator.js), since the library expects some methods to be available, as well as one of the [included generators](https://github.com/api-platform/create-client/blob/main/src/generators/BaseGenerator.j) to make your own. ## Usage ```shell -generate-api-platform-client -g "$(pwd)/path/to/custom/generator.js" -t "$(pwd)/path/to/templates" +npm init @api-platform/client -g "$(pwd)/path/to/custom/generator.js" -t "$(pwd)/path/to/templates" ``` The `-g` argument can point to any resolvable node module which means it can be a package dependency of the current project as well as any js file. ## Example -Client Generator makes use of the [Handlebars](https://handlebarsjs.com/) template engine. You can use any programming language or file type. Your generator can also pass data to your templates in any shape you want. +Create Client makes use of the [Handlebars](https://handlebarsjs.com/) template engine. You can use any programming language or file type. Your generator can also pass data to your templates in any shape you want. In this example, we'll create a simple [Rust](https://www.rust-lang.org) file defining a new `struct` and creating some instances of this `struct`. @@ -22,7 +22,7 @@ In this example, we'll create a simple [Rust](https://www.rust-lang.org) file de ```js // ./Generator.js -import BaseGenerator from "@api-platform/client-generator/lib/generators/BaseGenerator"; +import BaseGenerator from "@api-platform/create-client/lib/generators/BaseGenerator"; export default class extends BaseGenerator { constructor(params) { @@ -94,7 +94,7 @@ fn main() { Then we can use our generator: ```shell -generate-api-platform-client https://demo.api-platform.com out/ -g "$(pwd)/Generator.js" -t "$(pwd)/template" +npm init @api-platform/client https://demo.api-platform.com out/ -g "$(pwd)/Generator.js" -t "$(pwd)/template" ``` which will produces: diff --git a/client-generator/images/client-generator-demo.gif b/create-client/images/client-generator-demo.gif similarity index 100% rename from client-generator/images/client-generator-demo.gif rename to create-client/images/client-generator-demo.gif diff --git a/client-generator/images/nextjs/client-generator-nextjs-list.png b/create-client/images/nextjs/client-generator-nextjs-list.png similarity index 100% rename from client-generator/images/nextjs/client-generator-nextjs-list.png rename to create-client/images/nextjs/client-generator-nextjs-list.png diff --git a/client-generator/images/nextjs/client-generator-nextjs-show.png b/create-client/images/nextjs/client-generator-nextjs-show.png similarity index 100% rename from client-generator/images/nextjs/client-generator-nextjs-show.png rename to create-client/images/nextjs/client-generator-nextjs-show.png diff --git a/client-generator/images/nuxtjs/client-generator-nuxtjs-edit.png b/create-client/images/nuxtjs/client-generator-nuxtjs-edit.png similarity index 100% rename from client-generator/images/nuxtjs/client-generator-nuxtjs-edit.png rename to create-client/images/nuxtjs/client-generator-nuxtjs-edit.png diff --git a/client-generator/images/nuxtjs/client-generator-nuxtjs-list.png b/create-client/images/nuxtjs/client-generator-nuxtjs-list.png similarity index 100% rename from client-generator/images/nuxtjs/client-generator-nuxtjs-list.png rename to create-client/images/nuxtjs/client-generator-nuxtjs-list.png diff --git a/client-generator/images/react-native/client-generator-react-native-add.png b/create-client/images/react-native/client-generator-react-native-add.png similarity index 100% rename from client-generator/images/react-native/client-generator-react-native-add.png rename to create-client/images/react-native/client-generator-react-native-add.png diff --git a/client-generator/images/react-native/client-generator-react-native-delete.png b/create-client/images/react-native/client-generator-react-native-delete.png similarity index 100% rename from client-generator/images/react-native/client-generator-react-native-delete.png rename to create-client/images/react-native/client-generator-react-native-delete.png diff --git a/client-generator/images/react-native/client-generator-react-native-list.png b/create-client/images/react-native/client-generator-react-native-list.png similarity index 100% rename from client-generator/images/react-native/client-generator-react-native-list.png rename to create-client/images/react-native/client-generator-react-native-list.png diff --git a/client-generator/images/react-native/client-generator-react-native-show.png b/create-client/images/react-native/client-generator-react-native-show.png similarity index 100% rename from client-generator/images/react-native/client-generator-react-native-show.png rename to create-client/images/react-native/client-generator-react-native-show.png diff --git a/client-generator/images/react/client-generator-react-delete.png b/create-client/images/react/client-generator-react-delete.png similarity index 100% rename from client-generator/images/react/client-generator-react-delete.png rename to create-client/images/react/client-generator-react-delete.png diff --git a/client-generator/images/react/client-generator-react-edit.png b/create-client/images/react/client-generator-react-edit.png similarity index 100% rename from client-generator/images/react/client-generator-react-edit.png rename to create-client/images/react/client-generator-react-edit.png diff --git a/client-generator/images/react/client-generator-react-list-pagination.png b/create-client/images/react/client-generator-react-list-pagination.png similarity index 100% rename from client-generator/images/react/client-generator-react-list-pagination.png rename to create-client/images/react/client-generator-react-list-pagination.png diff --git a/client-generator/images/react/client-generator-react-list.png b/create-client/images/react/client-generator-react-list.png similarity index 100% rename from client-generator/images/react/client-generator-react-list.png rename to create-client/images/react/client-generator-react-list.png diff --git a/client-generator/images/react/client-generator-react-show.png b/create-client/images/react/client-generator-react-show.png similarity index 100% rename from client-generator/images/react/client-generator-react-show.png rename to create-client/images/react/client-generator-react-show.png diff --git a/client-generator/index.md b/create-client/index.md similarity index 82% rename from client-generator/index.md rename to create-client/index.md index c3441f09424..12e40437e2f 100644 --- a/client-generator/index.md +++ b/create-client/index.md @@ -1,9 +1,9 @@ -# The API Platform Client Generator +# API Platform Create Client -Client Generator is the fastest way to scaffold fully featured webapps +Create Client is the fastest way to scaffold fully featured webapps and native mobile apps from APIs supporting the [Hydra](http://www.hydra-cg.com/) or [OpenAPI](https://www.openapis.org/) format. -![Screencast](images/client-generator-demo.gif) +![Screencast](images/create-client-demo.gif) ## Generated React and React Native Apps, Updated in Real Time @@ -18,7 +18,7 @@ It is able to generate apps using the following frontend stacks: - [Vue.js](vuejs.md) - [Or bring your custom generator](custom.md) -Client Generator works especially well with APIs built with the [API Platform](https://api-platform.com) framework. +Create Client works especially well with APIs built with the [API Platform](https://api-platform.com) framework. ## Features diff --git a/create-client/nextjs.md b/create-client/nextjs.md new file mode 100644 index 00000000000..1ccd57624e3 --- /dev/null +++ b/create-client/nextjs.md @@ -0,0 +1,83 @@ +# Next.js Generator + +![List screenshot](images/nextjs/create-client-nextjs-list.png) + +The Next.js generator scaffolds components for Server Side Rendered applications using [Next.js](https://nextjs.org/). + +## Install + +The easiest way to get started is to install [the API Platform distribution](../distribution/index.md). +It contains a Next.js skeleton generated with Create Next App, +a development Docker container to serve the webapp, and all the API Platform components you may need, including an API server +supporting Hydra and OpenAPI. + +If you use API Platform, jump to the next section! + +Alternatively, create a Next.js application by executing: + +```console +# using pnpm (recommended) +pnpm create next-app --typescript +# or using npm +npm init next-app --typescript +# or using yarn +yarn create next-app --typescript +``` + +Install the required dependencies: + +```console +# using pnpm +pnpm install isomorphic-unfetch formik react-query +# or using npm +npm install isomorphic-unfetch formik react-query +# or using yarn +yarn add isomorphic-unfetch formik react-query +``` + +## Generating Routes + +If you use the API Platform distribution, generating all the code you need for a given resource is as simple as running the following command: + +```console +docker compose exec pwa \ + pnpm create @api-platform/client --resource book -g next +``` + +Omit the resource flag to generate files for all resource types exposed by the API. + +If you don't use the standalone installation, run the following command instead: + +```console +# using pnpm +pnpm create @api-platform/client https://demo.api-platform.com . --generator next --resource book +# or using npm +npm init @api-platform/client https://demo.api-platform.com . --generator next --resource book +# or using yarn +yarn create @api-platform/client https://demo.api-platform.com . --generator next --resource book +``` + +Replace the URL by the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + +The code has been generated, and is ready to be executed! + +## Starting the Project + +You can launch the server with + +```console +# using pnpm +pnpm dev +# or using npm +npm run dev +# or using yarn +yarn dev +``` + +Go to `http://localhost:3000/books/` to start using your app. + +## Screenshots + +![List](images/nextjs/create-client-nextjs-list.png) +![Show](images/nextjs/create-client-nextjs-show.png) diff --git a/client-generator/nuxtjs.md b/create-client/nuxtjs.md similarity index 81% rename from client-generator/nuxtjs.md rename to create-client/nuxtjs.md index e741a78b45f..87dd97a7b92 100644 --- a/client-generator/nuxtjs.md +++ b/create-client/nuxtjs.md @@ -1,22 +1,15 @@ # Nuxt.js Generator -The Nuxt.js Client Generator generates components for Server Side Rendered applications using [Nuxt.js](https://nuxtjs.org/) and [Vuetify](https://vuetifyjs.com/). +The Nuxt.js generator scaffolds components for Server Side Rendered applications using [Nuxt.js](https://nuxtjs.org/) and [Vuetify](https://vuetifyjs.com/). ## Install ### Nuxt Create a [Nuxt.js application](https://nuxtjs.org/guides/get-started/installation#using-create-nuxt-app). -The easiest way is to execute: ```console -npx create-nuxt-app your-app-name -``` - -or: - -```console -yarn create nuxt-app your-app-name +npm init nuxt-app your-app-name ``` It will ask you some questions, you can use these answers: @@ -24,7 +17,7 @@ It will ask you some questions, you can use these answers: ```console Project name: your-app-name Programming language: JavaScript -Package manager: Yarn +Package manager: NPM UI framework: Vuetify.js Nuxt.js modules: None Linting tools: Prettier, Lint staged files @@ -38,8 +31,8 @@ Deployment target: Static (Static/JAMStack hosting) Install required dependencies: ```console -yarn add moment lodash vue-i18n vuelidate vuex-map-fields nuxt-i18n -yarn add --dev @nuxtjs/vuetify @nuxtjs/fontawesome +npm install moment lodash vue-i18n vuelidate vuex-map-fields nuxt-i18n +npm install --dev @nuxtjs/vuetify @nuxtjs/fontawesome ``` ## Updating Nuxt Config @@ -61,11 +54,11 @@ Update your `nuxt.config.js` with following: ## Generating Routes ```console -npx @api-platform/client-generator https://demo.api-platform.com . --generator nuxt -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client https://demo.api-platform.com . --generator nuxt ``` Replace the URL by the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. **Note:** Omit the resource flag to generate files for all resource types exposed by the API. @@ -148,12 +141,12 @@ export default { You can launch the server with: ```console -yarn dev +npm run dev ```` Go to `https://localhost:3000/books/` to start using your app. ## Screenshots -![List](images/nuxtjs/client-generator-nuxtjs-list.png) -![Edit](images/nuxtjs/client-generator-nuxtjs-edit.png) +![List](images/nuxtjs/create-client-nuxtjs-list.png) +![Edit](images/nuxtjs/create-client-nuxtjs-edit.png) diff --git a/client-generator/quasar.md b/create-client/quasar.md similarity index 90% rename from client-generator/quasar.md rename to create-client/quasar.md index 77b48f850df..8efcb7f4587 100644 --- a/client-generator/quasar.md +++ b/create-client/quasar.md @@ -11,11 +11,12 @@ cd my-app In the app directory, generate the files for the resource you want: ```console -npx @api-platform/client-generator https://demo.api-platform.com src/ --generator quasar --resource foo -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client https://demo.api-platform.com src/ --generator quasar --resource foo ``` Replace the URL by the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + Omit the resource flag to generate files for all resource types exposed by the API. The code is ready to be executed! Register the generated routes: diff --git a/client-generator/react-native.md b/create-client/react-native.md similarity index 68% rename from client-generator/react-native.md rename to create-client/react-native.md index 7aed50fb083..23c5d459a1f 100644 --- a/client-generator/react-native.md +++ b/create-client/react-native.md @@ -1,17 +1,16 @@ # React Native generator -![List](images/react-native/client-generator-react-native-list.png) +![List](images/react-native/create-client-react-native-list.png) ## Install -To use this generator you need [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) (or [npm](https://www.npmjs.com/)) installed. -To run the command line tool, we also recommend using [npx](https://www.npmjs.com/package/npx). +To use this generator you need [Node.js](https://nodejs.org/). Create a React Native application using [Expo CLI](https://docs.expo.io/workflow/expo-cli/): ```console -yarn global add expo-cli -expo init my-app +npm install -g expo-cli +npm init expo-app my-app ``` When asked, choose to use the blank template, then move to the created directory: @@ -23,7 +22,7 @@ cd my-app Install the required dependencies: ```console -yarn add redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux react-native-vector-icons prop-types whatwg-url buffer react-native-event-source react-native-gesture-handler react-native-reanimated react-native-screens +npm install redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux react-native-vector-icons prop-types whatwg-url buffer react-native-event-source react-native-gesture-handler react-native-reanimated react-native-screens ```` ## Generating a Native App @@ -31,11 +30,12 @@ yarn add redux react-redux redux-thunk redux-form react-native-elements react-na In the app directory, generate the files for the resource you want: ```console -npx @api-platform/client-generator https://demo.api-platform.com . --generator react-native --resource book -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client https://demo.api-platform.com . --generator react-native --resource book ``` Replace the URL with the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + Omit the resource flag to generate files for all resource types exposed by the API. Create a `Router.js` file to import all routes: @@ -111,5 +111,5 @@ expo start ## Screenshots in iOS Simulator -![List](images/react-native/client-generator-react-native-list.png) ![Show](images/react-native/client-generator-react-native-show.png) -![Add](images/react-native/client-generator-react-native-add.png) ![Delete](images/react-native/client-generator-react-native-delete.png) +![List](images/react-native/create-client-react-native-list.png) ![Show](images/react-native/create-client-react-native-show.png) +![Add](images/react-native/create-client-react-native-add.png) ![Delete](images/react-native/create-client-react-native-delete.png) diff --git a/client-generator/react.md b/create-client/react.md similarity index 57% rename from client-generator/react.md rename to create-client/react.md index 9993598b827..41edbdd2016 100644 --- a/client-generator/react.md +++ b/create-client/react.md @@ -1,8 +1,8 @@ # React Generator -![List screenshot](images/react/client-generator-react-list.png) +![List screenshot](images/react/create-client-react-list.png) -The React Client Generator generates a Single Page Application or a Progressive Web App built with battle-tested libraries +The React generator scaffolds a Single Page Application or a Progressive Web App built with battle-tested libraries from the ecosystem: * [React](https://reactjs.org/) @@ -16,39 +16,38 @@ It is designed to generate code that works seamlessly with [Facebook's Create Re Bootstrap a React application: ```console -npx create-react-app --template typescript client -cd client +npm init react-app --template typescript my-app +cd my-app ``` Install the required dependencies: ```console -yarn add react-router-dom react-hook-form +npm install react-router-dom react-hook-form ``` Optionally, install Bootstrap and Font Awesome to get an app that looks good: ```console -yarn add bootstrap font-awesome +npm install bootstrap font-awesome ``` Finally, start the integrated web server: ```console -yarn start +npm run start ``` ## Generating a Web App ```console -npx @api-platform/client-generator https://demo.api-platform.com src/ --generator next --resource book -# Replace the URL by the entrypoint of your Hydra-enabled API -# Omit the resource flag to generate files for all resource types exposed by the API. -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client https://demo.api-platform.com src/ --generator next --resource book ``` -> Note: On the [API Platform distribution](https://github.com/api-platform/api-platform), you can run -> `generate-api-platform-client` instead of `npx @api-platform/client-generator`. +Replace the URL by the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + +Omit the resource flag to generate files for all resource types exposed by the API. The code has been generated, and is ready to be executed! @@ -88,8 +87,8 @@ Go to `https://localhost/books/` to start using your app. ## Screenshots -![List](images/react/client-generator-react-list.png) -![Pagination](images/react/client-generator-react-list-pagination.png) -![Show](images/react/client-generator-react-show.png) -![Edit](images/react/client-generator-react-edit.png) -![Delete](images/react/client-generator-react-delete.png) +![List](images/react/create-client-react-list.png) +![Pagination](images/react/create-client-react-list-pagination.png) +![Show](images/react/create-client-react-show.png) +![Edit](images/react/create-client-react-edit.png) +![Delete](images/react/create-client-react-delete.png) diff --git a/client-generator/troubleshooting.md b/create-client/troubleshooting.md similarity index 93% rename from client-generator/troubleshooting.md rename to create-client/troubleshooting.md index cdb7143f561..f2ab81e6a04 100644 --- a/client-generator/troubleshooting.md +++ b/create-client/troubleshooting.md @@ -3,10 +3,10 @@ ## Self-Signed TLS Certificate If you are running API Platform on development machine which does not have valid TLS certificate, -add `NODE_TLS_REJECT_UNAUTHORIZED=0` before running client-generator: +add `NODE_TLS_REJECT_UNAUTHORIZED=0` before running create-client: ```console -NODE_TLS_REJECT_UNAUTHORIZED=0 npx @api-platform/client-generator --generator typescript https://127.0.0.1:8000/api src/ +NODE_TLS_REJECT_UNAUTHORIZED=0 npm init @api-platform/client --generator typescript https://127.0.0.1:8000/api src/ ``` ## Authenticated API diff --git a/client-generator/typescript.md b/create-client/typescript.md similarity index 64% rename from client-generator/typescript.md rename to create-client/typescript.md index e42a12719c2..affa4fd5963 100644 --- a/client-generator/typescript.md +++ b/create-client/typescript.md @@ -3,16 +3,18 @@ The TypeScript Generator allows you to create [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html) that you can embed in any TypeScript-enabled project (React, Vue.js, Angular..). -To do so, run the client generator: +To do so, run the generator: ```console -npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/ --resource foo +npm init @api-platform/client --generator typescript https://demo.api-platform.com src/ --resource foo # Replace the URL with the entrypoint of your Hydra-enabled API. -# "src/" represents where the interfaces will be generated. -# Omit the resource flag to generate files for all resource types exposed by the API. -# You can also use an OpenAPI documentation with `-f openapi3`. ``` +`src/` is where the interfaces will be generated. + +Omit the resource flag to generate files for all resource types exposed by the API. +You can also use an OpenAPI documentation with `-f openapi3`. + This command parses the Hydra documentation and creates one `.ts` file for each API Resource you have defined in your application, in the `interfaces` subfolder. **Note:** If you are not sure what the entrypoint is, see [Troubleshooting](troubleshooting.md). @@ -22,7 +24,7 @@ This command parses the Hydra documentation and creates one `.ts` file for each Assuming you have 2 resources in your application, `Foo` and `Bar`, when you run: ```console -npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/ +npm init @api-platform/client --generator typescript https://demo.api-platform.com src/ ``` You will obtain 2 `.ts` files arranged as following: diff --git a/client-generator/vuejs.md b/create-client/vuejs.md similarity index 74% rename from client-generator/vuejs.md rename to create-client/vuejs.md index af77c3be7ff..c5800c6b781 100644 --- a/client-generator/vuejs.md +++ b/create-client/vuejs.md @@ -10,23 +10,25 @@ cd my-app Install the required dependencies: ```console -yarn add vuex@3 vuex-map-fields lodash +npm install vuex@3 vuex-map-fields lodash ``` Optionally, install Bootstrap and Font Awesome to get an app that looks good: ```console -yarn add bootstrap font-awesome +npm install add bootstrap font-awesome ``` To generate all the code you need for a given resource run the following command: ```console -npx @api-platform/client-generator https://demo.api-platform.com src/ --generator vue --resource book -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client https://demo.api-platform.com src/ --generator vue --resource book ``` -Replace the URL with the entrypoint of your Hydra-enabled API. Omit the resource flag to generate files for all resource types exposed by the API. +Replace the URL with the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + +Omit the resource flag to generate files for all resource types exposed by the API. The code is ready to be executed! Register the generated routes and store modules. Here is an example: diff --git a/client-generator/vuetify.md b/create-client/vuetify.md similarity index 81% rename from client-generator/vuetify.md rename to create-client/vuetify.md index 57330d5afdb..f6972dccbcf 100644 --- a/client-generator/vuetify.md +++ b/create-client/vuetify.md @@ -2,25 +2,27 @@ ## Install With Docker -If you use the API Platform distribution with Docker, first you have to add the [Vue CLI](https://cli.vuejs.org/guide/) to the `yarn global add` command in `pwa/Dockerfile`: +If you use the API Platform distribution with Docker, first you have to add the [Vue CLI](https://cli.vuejs.org/guide/) to the Docker image. + +In the `dev` stage of `pwa/Dockerfile`, add this line: ```dockerfile -RUN yarn global add @api-platform/client-generator @vue/cli @vue/cli-service-global +RUN pnpm install -g @vue/cli @vue/cli-service-global ``` -Rebuild your containers to install the Vue CLI in docker client container. +Then, rebuild your containers. -Remove the directories `client\src\` and `client\public\` and the files `client\package.json\` and `client\yarn.lock\` (because the distribution comes with a prebuilt Next.js app.) +Delete the content of the `pwa\` directory (the distribution comes with a prebuilt Next.js app). Create a new Vue App and install vuetify and other vue packages: ```console -docker compose exec client \ +docker compose exec pwa \ vue create -d . -docker compose exec client \ +docker compose exec pwa \ vue add vuetify -docker compose exec client \ - yarn add router lodash moment vue-i18n vue-router vuelidate vuex vuex-map-fields +docker compose exec pwa \ + pnpm install router lodash moment vue-i18n vue-router vuelidate vuex vuex-map-fields ``` Update the entrypoint: @@ -42,11 +44,11 @@ Update the scripts part of the new `package.json`: Rebuild the docker containers again to install the Vue App and start the vue server. -Generate the vuetify components with the client generator: +Generate the vuetify components with the following command: ```console -docker compose exec client \ - generate-api-platform-client -g vuetify --resource book +docker compose exec pwa \ + pnpm create @api-platform/client -g vuetify --resource book ``` Omit the resource flag to generate files for all resource types exposed by the API. @@ -67,19 +69,19 @@ vue add vuetify Install the required dependencies: ```console -yarn add router lodash moment vue-i18n vue-router vuelidate vuex vuex-map-fields - -yarn global add @api-platform/client-generator +npm install router lodash moment vue-i18n vue-router vuelidate vuex vuex-map-fields ``` In the app directory, generate the files for the resource you want: ```console -npx @api-platform/client-generator -g vuetify https://demo.api-platform.com src/ -# You can also use an OpenAPI documentation with `-f openapi3`. +npm init @api-platform/client -g vuetify https://demo.api-platform.com src/ ``` -Replace the URL with the entrypoint of your Hydra-enabled API. Omit the resource flag to generate files for all resource types exposed by the API. +Replace the URL with the entrypoint of your Hydra-enabled API. +You can also use an OpenAPI documentation with `-f openapi3`. + +Omit the resource flag to generate files for all resource types exposed by the API. ## Generating the VueJS Web App @@ -167,7 +169,7 @@ export default new VueI18n({ }); ``` -Update your App.vue: +Update your `App.vue`: ```vue diff --git a/distribution/index.md b/distribution/index.md index f9ecb3c3e69..d3fbb23d3ba 100644 --- a/distribution/index.md +++ b/distribution/index.md @@ -19,7 +19,7 @@ API Platform also provides ambitious **JavaScript** tools to create web and mobi The easiest and most powerful way to get started is [to download the API Platform distribution](https://github.com/api-platform/api-platform/releases). It contains: * the API skeleton, including [the Core library](../core/index.md), [the Symfony framework](https://symfony.com/) ([optional](../core/bootstrap.md)) and [the Doctrine ORM](https://www.doctrine-project.org/projects/orm.html) ([optional](../core/extending.md)) -* [the client scaffolding tool](../client-generator/) to generate [Next.js](../client-generator/ +* [the client scaffolding tool](../create-client/) to generate [Next.js](../create-client/ ) web applications from the API documentation ([Nuxt.js](https://nuxtjs.org/), [Vue](https://vuejs.org/), [Create React App](https://reactjs.org), [React Native](https://facebook.github.io/react-native/), [Quasar](https://quasar.dev/) and [Vuetify](https://vuetifyjs.com/) are also supported) * [a beautiful admin interface](../admin/), built on top of React Admin, dynamically created by parsing the API documentation * all you need to [create real-time and async APIs using the Mercure protocol](../core/mercure.md) @@ -93,7 +93,7 @@ This starts the following services: |----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | caddy | [Caddy web server](caddy.md) with the [Mercure](../core/mercure.md) (real-time and async) and [Vulcain](https://vulcain.rocks) (relations preloading) modules | | php | The API with PHP 8, Composer and sensitive configs | -| pwa | Next.js webapp with API Platform Admin and Client Generator preinstalled | +| pwa | Next.js project compatible with Create Client and having Admin preinstalled | | database | PostgreSQL database server | The following components are available: @@ -187,7 +187,7 @@ symfony serve ``` All JavaScript components are also [available as standalone libraries](https://github.com/api-platform?language=javascript) -installable with npm or Yarn. +installable with npm (or any other package manager). **Note:** when installing API Platform this way, the API will be exposed as the `/api/` path. You need to open `http://localhost:8000/api/` to see the API documentation. If you are deploying API Platform directly on an Apache or NGINX webserver and getting a 404 error on opening this link, you will need to enable the [rewriting rules](https://symfony.com/doc/current/setup/web_server_configuration.html) for your specific webserver software. @@ -744,14 +744,14 @@ occurs**. ## A Next.js Web App -API Platform also has an awesome [client generator](../client-generator/index.md) able to scaffold fully working Next.js, Nuxt.js, React/Redux, Vue.js, Quasar and Vuetify Progressive Web Apps that you can easily tune and customize. The generator also supports +API Platform also has an awesome [client generator](../create-client/index.md) able to scaffold fully working Next.js, Nuxt.js, React/Redux, Vue.js, Quasar and Vuetify Progressive Web Apps that you can easily tune and customize. The generator also supports [React Native](https://facebook.github.io/react-native/) if you prefer to leverage all capabilities of mobile devices. The distribution comes with a skeleton ready to welcome the [Next.js](https://nextjs.org/) flavor of the generated code. To bootstrap your app, run: ```console docker compose exec pwa \ - generate-api-platform-client + pnpm create @api-platform/client ``` Open `https://localhost/books/` in your browser: @@ -759,13 +759,13 @@ Open `https://localhost/books/` in your browser: ![The Next.js Progressive Web App](images/api-platform-2.6-pwa-react.png) You can also choose to generate the code for a specific resource with the `--resource` argument (example: -`generate-api-platform-client --resource books`). +`pnpm create @api-platform/client --resource books`). The generated code contains a list (including pagination), a delete button, a creation and an edition form. It also includes [Bootstrap](https://getbootstrap.com) markup and [ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to make the app usable by people with disabilities. -If you prefer to generate a PWA built on top of another frontend stack, read [the dedicated documentation](../client-generator/index.md). +If you prefer to generate a PWA built on top of another frontend stack, read [the dedicated documentation](../create-client/index.md). ## Hooking Your Own Business Logic diff --git a/extra/contribution-guides.md b/extra/contribution-guides.md index 951fe0e510b..179a4ed1364 100644 --- a/extra/contribution-guides.md +++ b/extra/contribution-guides.md @@ -3,7 +3,7 @@ 1. [API Platform Core Library](https://github.com/api-platform/core/blob/main/CONTRIBUTING.md) 2. [API Platform Schema Generator](https://github.com/api-platform/schema-generator/blob/main/CONTRIBUTING.md) 3. [API Platform Admin](https://github.com/api-platform/admin/blob/master/CONTRIBUTING.md) -4. [API Platform CRUD Generator](https://github.com/api-platform/client-generator/blob/master/CONTRIBUTING.md) +4. [API Platform CRUD Generator](https://github.com/api-platform/create-client/blob/master/CONTRIBUTING.md) **To report a security issue, please refer to [the dedicated document](security.md).** diff --git a/extra/philosophy.md b/extra/philosophy.md index 8a762c8c3c9..de82e01691a 100644 --- a/extra/philosophy.md +++ b/extra/philosophy.md @@ -28,7 +28,7 @@ API Platform makes modern development easy and fun again: * [Start by **creating a web API**](../distribution/index.md) exposing structured data that can be understood by any compliant client such as your apps but also search engines (JSON-LD with Schema.org vocabulary). This API is the central and unique entry point to access and modify data. It also encapsulates the whole business logic. -* [Then **create as many clients as you want using frontend technologies you love**](../client-generator/index.md): a JavaScript +* [Then **create as many clients as you want using frontend technologies you love**](../create-client/index.md): a JavaScript webapp built with React or with Vue querying the API but also a native iOS or Android app, or even a desktop application. Clients only display data and forms. diff --git a/outline.yaml b/outline.yaml index 3fc443cb8ae..655a603d9d4 100644 --- a/outline.yaml +++ b/outline.yaml @@ -6,7 +6,7 @@ chapters: - testing - debugging - caddy - - title: The API Component + - title: Core path: core items: - index @@ -55,13 +55,13 @@ chapters: - bootstrap - configuration - migrate-from-fosrestbundle - - title: The Schema Generator Component + - title: Schema Generator path: schema-generator items: - index - getting-started - configuration - - title: The Admin Component + - title: Admin path: admin items: - index @@ -76,8 +76,8 @@ chapters: - performance - customizing - components - - title: The Client Generator Component - path: client-generator + - title: Create Client + path: create-client items: - index - nextjs