docs: Revamp API Platform Admin docs #2141

slax57 · 2025-03-07T18:10:50Z

This PR aims at generally improving the API Platform Admin documentation, notably:

Updating the code, links, and screenshots
Reorganizing the pages to provide a linear, guided read-through for newcomers (see below)
Improve documentation regarding the ways to customize the generated Admin, most notably showcasing advanced customization using React Admin components
Fix minor issues found while proof-reading

This PR relies on customization examples brought by api-platform/admin#600

Here is the new TOC I implemented:

The API Platform Admin
i. General intro about what API Platform Admin is
ii. When can I use it
iii. Introduce React Admin
iv. Feature @fzaninotto 's presentation given at the API Platform Conference 2024
v. List features offered by the Admin
Getting Started
i. Introduce HydraAdmin
ii. Introduce OpenApiAdmin
Customizing the Schema
i. Show how to customize the Admin with just PHP changes
ii. Includes the 'Using the Schema.org Vocabulary' content
Customizing Guessers
i. Learn how to use FieldGuesser and InputGuesser
ii. Includes current section 'Customizing the Admin'
Customizing the Admin
i. Provide examples of more advanced customization, leveraging React Admin components
Handling Relations
Validating Forms
Realtime Updates
Authentication
Handling File Upload
Performance -> renamed to Performance Tips
Components -> renamed to Components Reference

TODO

Finish the rewrite
update the menu
Much proof-reading

How to test

Clone https://github.com/api-platform/docs-website
Edit docs-versions.txt to add a version named revamp-admin-docs (name of the branch of this PR)
Edit hugo.toml to add a version named revamp-admin-docs with path vrevamp-admin-docs
Install hugo on your machine (sudo apt install hugo)
Follow the instructions from the README.md of the docs-website repo
Run hugo serve
Browse http://localhost:1313/docs/vrevamp-admin-docs/admin/

fzaninotto

Awesome work! Kudos for that.

The new chapters are 💯 . You helped improve the old ones, but some passages are still hard to follow.

fzaninotto · 2025-03-12T20:38:58Z

admin/components.md

@@ -1,19 +1,23 @@
-# Components
+# Components Reference


I don't understand the "Resource Components" title below. Also, I'm not sure we need this title level. Can't we directly list the components as h2? After all, we're in a components documentation...

fzaninotto · 2025-03-12T20:39:19Z

admin/components.md

-(for Hydra documented APIs, use the [HydraAdmin component](components.md#hydraadmin) instead,
-for OpenAPI documented APIs, use the [OpenApiAdmin component](components.md#openapiadmin) instead).
-It also creates a [schema analyzer](components.md#schema-analyzer) context, where the `schemaAnalyzer` service (for getting information about the provided API documentation) is stored.
+`<AdminGuesser>` renders automatically an [`<Admin>` component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser`.


Suggested change

`<AdminGuesser>` renders automatically an [`<Admin>` component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser`.

`<AdminGuesser>` automatically renders an [`<Admin>` component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser`.

fzaninotto · 2025-03-12T20:40:19Z

admin/components.md


-`<AdminGuesser>` renders all exposed resources by default, but you can choose what resource you want to render by passing [ResourceGuesser components](components.md#resourceguesser) as children.
-Deprecated resources are hidden by default, but you can add them back using an explicit `<ResourceGuesser>` component.
+**Tip:** For Hydra documented APIs, use the [`<HydraAdmin>` component](#hydraadmin) instead.


This I don't understand. Should I use AdminGuesser or HydraAdmin?

fzaninotto · 2025-03-12T20:41:15Z

admin/components.md

+
+**Tip:** Deprecated resources are hidden by default, but you can add them back using an explicit `<ResourceGuesser>` component.
+
+```tsx


I'd move this piece of code earlier, just after the first sentence of the section.

fzaninotto · 2025-03-12T20:42:09Z

admin/components.md

-// App.js
+**Tip:** For OpenAPI documented APIs, use the [`<OpenApiAdmin>` component](#openapiadmin) instead.
+
+It also creates a [schema analyzer](#hydra-schema-analyzer) context, where the `schemaAnalyzer` service (for getting information about the provided API documentation) is stored.


This is confusing: AdminGuesser creates a schema analyzer, but it also accepts a schemaAnalyzer prop?

I kept that part from the previous version of the doc. But now that I think about it, it doesn't bring much, and the schema analyzer context is never mentioned again in the docs, so unless we decide to properly document it at some point, it's best to remove this sentence altogether IMHO.

fzaninotto · 2025-03-12T20:55:06Z

admin/handling-relations.md

@@ -11,12 +11,10 @@ If a relation is an array of [embeddeds or an embedded](../core/serialization.md
 The embedded data will be displayed as text field and editable as text input: the admin cannot determine the fields present in it.
 To display the fields you want, see [this section](handling-relations.md#display-a-field-of-an-embedded-relation).


use the section name in the link instead of "this section"

fzaninotto · 2025-03-12T20:55:58Z

admin/handling-relations.md

-You can also ask the admin to automatically replace the embedded resources' data by their IRI,
-by setting the `useEmbedded` parameter of the Hydra data provider to `false`.
-Embedded data is inserted to a local cache: it will not be necessary to make more requests if you reference some fields of the embedded resource later on.
+You can also ask the admin to return the embedded resources' IRI instead of the full record, by setting the `useEmbedded` parameter of the Hydra data provider to `false`.


Not sure I understand what this means. Could you maybe give an example response?

For the same reason, no, unfortunately :(

fzaninotto · 2025-03-12T21:01:01Z

admin/authentication-support.md

@@ -20,7 +27,7 @@ const getHeaders = () =>
    : {};
 ```

-Extend the Hydra fetch function with custom headers for authentication.
+Then, extend the Hydra `fetch` function to use the `getHeaders` function to add the `Authorization` header to the requests.

 ```typescript
 const fetchHydra = (url, options = {}) =>


missing import statement for the baseFetchHydra

fzaninotto · 2025-03-12T21:02:14Z

admin/authentication-support.md


-Redirect users to a `/login` path, if no token is available in the `localStorage`.
+Then, we'll create a `<RedirectToLogin>` component, that will redirect users to the `/login` route if no token is available in the `localStorage`, and perform the introspection otherwise.


perform the introspection

Not sure what this means. And how does this concern authentication?

I basically calls the dataProvider's introspect function. To be fair I'm not 100% sure this is necessary, at least with modern React Admin which should already redirect to the login page if no token is available, but I'm not tooled enough to neither confirm nor infirm this.

fzaninotto · 2025-03-12T21:02:48Z

admin/authentication-support.md

-Extend the `parseHydraDocumentaion` function from the [API Doc Parser library](https://github.com/api-platform/api-doc-parser)
-to handle the documentation parsing. Customize it to clear
-expired tokens when encountering unauthorized `401` response.
+We will customize it to clear expired tokens when encountering unauthorized `401` response.

 ```typescript
 const apiDocumentationParser = (setRedirectToLogin) => async () => {


missing import for the function to extend

slax57 added 3 commits March 7, 2025 11:43

docs: revamp the admin index page

505e82f

docs: revamp the getting started section

c873a42

docs: revamp schema.org doc

db1cb96

slax57 mentioned this pull request Mar 7, 2025

[Storybook] Improve Storybook examples api-platform/admin#600

Merged

slax57 added 4 commits March 10, 2025 11:24

docs: revamp the customizing the guessers doc

a9ac94e

docs: add new customizing the admin page

73a1fbe

docs: update handling relations doc

ade232e

docs: update validation doc

9dbcf96

slax57 force-pushed the revamp-admin-docs branch from 1fca087 to 9dbcf96 Compare March 10, 2025 17:34

slax57 added 5 commits March 12, 2025 12:09

docs: update file upload doc

52a2656

docs: update performance doc

aeb023a

[no ci] docs: update components reference doc

6d4f5a7

docs: update authentication doc

24c87b8

fix linter issues

8bfb644

slax57 changed the title ~~[Doc] Revamp API Platform Admin docs~~ docs: Revamp API Platform Admin docs Mar 12, 2025

slax57 added 3 commits March 12, 2025 18:24

doc: handling relations: add more links to RA doc

371d14c

comply with foolish linter rules

fe56516

fix links and make navigation more consistent

de13c04

fzaninotto requested changes Mar 12, 2025

View reviewed changes

slax57 added 11 commits March 13, 2025 10:55

fix linter blockquote issue

5890a02

docs: apply review on components reference

ea4865a

docs: apply review on handling relations

dc28485

docs: revamp the handling relations doc

17b67e8

docs: apply review on authentication support doc

9036ebe

Merge remote-tracking branch 'origin/4.1' into revamp-admin-docs

25b56df

docs: update the admin outline (menu)

2f2ffbb

fix linter again and again

2348e35

docs: add section about Validation With React Admin Inputs

078a77e

docs: schema: add screenshots for name instead of IRI

3254a5d

docs: minor updates after self-review

ae0b3a2

slax57 added 4 commits March 14, 2025 18:59

docs: add sections about replacing field/input with RA components

932bfa4

docs: add request example in performance section

49ebea2

docs: fix all anchor links (because of hugo)

9c6b238

Merge remote-tracking branch 'origin/4.1' into revamp-admin-docs

f596da2

slax57 marked this pull request as ready for review March 14, 2025 18:20

slax57 added 2 commits March 17, 2025 11:42

fix releases.md lint issues

c1b8466

fix validation.md lint issues

427153f

djhi approved these changes Mar 17, 2025

View reviewed changes

fzaninotto approved these changes Mar 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Revamp API Platform Admin docs #2141

docs: Revamp API Platform Admin docs #2141

slax57 commented Mar 7, 2025 •

edited

Loading

fzaninotto left a comment

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

slax57 Mar 13, 2025

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

slax57 Mar 13, 2025

fzaninotto Mar 12, 2025

fzaninotto Mar 12, 2025

slax57 Mar 14, 2025

fzaninotto Mar 12, 2025

	`<AdminGuesser>` renders automatically an [`<Admin>` component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser`.
	`<AdminGuesser>` automatically renders an [`<Admin>` component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser`.


		Tip: Deprecated resources are hidden by default, but you can add them back using an explicit `<ResourceGuesser>` component.

		```tsx

		@@ -11,12 +11,10 @@ If a relation is an array of [embeddeds or an embedded](../core/serialization.md
		The embedded data will be displayed as text field and editable as text input: the admin cannot determine the fields present in it.
		To display the fields you want, see [this section](handling-relations.md#display-a-field-of-an-embedded-relation).


		Redirect users to a `/login` path, if no token is available in the `localStorage`.
		Then, we'll create a `<RedirectToLogin>` component, that will redirect users to the `/login` route if no token is available in the `localStorage`, and perform the introspection otherwise.

docs: Revamp API Platform Admin docs #2141

Are you sure you want to change the base?

docs: Revamp API Platform Admin docs #2141

Conversation

slax57 commented Mar 7, 2025 • edited Loading

TODO

How to test

fzaninotto left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slax57 commented Mar 7, 2025 •

edited

Loading