Skip to content

Commit dd24806

Browse files
alanpoulainalanpoulain
authored
feat(admin): add OpenAPI documentation (#1540)
1 parent 46edecd commit dd24806

File tree

7 files changed

+140
-61
lines changed

7 files changed

+140
-61
lines changed

‎admin/components.md

Lines changed: 78 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44

55
### AdminGuesser
66

7-
`<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` (for Hydra documented APIs,
8-
use the [HydraAdmin component](components.md#hydraadmin) instead).
7+
`<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`
8+
(for Hydra documented APIs, use the [HydraAdmin component](components.md#hydraadmin) instead,
9+
for OpenAPI documented APIs, use the [OpenApiAdmin component](components.md#openapiadmin) instead).
910
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.
1011

1112
`<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.
@@ -17,7 +18,6 @@ import { AdminGuesser, ResourceGuesser } from "@api-platform/admin";
1718

1819
const App = () => (
1920
<AdminGuesser
20-
entrypoint={entrypoint}
2121
dataProvider={dataProvider}
2222
authProvider={authProvider}>
2323
<ResourceGuesser
@@ -35,13 +35,12 @@ export default App;
3535

3636
#### Props
3737

38-
| Name | Type | Value | required | Description |
39-
|-------------------|--------------------|----------------|----------|----------------------------------------------------------------------------------|
40-
| dataProvider | object or function | - | yes | communicates with your API |
41-
| schemaAnalyzer | object | schemaAnalyzer | yes | retrieves resource type according to [Schema.org](https://schema.org) vocabulary |
42-
| children | node or function | - | no | - |
43-
| theme | object | theme | no | theme of your Admin App |
44-
| includeDeprecated | boolean | true or false | no | displays or not deprecated resources |
38+
| Name | Type | Value | required | Description |
39+
|-------------------|---------|----------------|----------|----------------------------------------------------------------------------------|
40+
| dataProvider | object | dataProvider | yes | communicates with your API |
41+
| schemaAnalyzer | object | schemaAnalyzer | yes | retrieves resource type according to [Schema.org](https://schema.org) vocabulary |
42+
| theme | object | theme | no | theme of your Admin App |
43+
| includeDeprecated | boolean | true or false | no | displays or not deprecated resources |
4544

4645
### ResourceGuesser
4746

@@ -55,7 +54,6 @@ import { AdminGuesser, ResourceGuesser } from "@api-platform/admin";
5554

5655
const App = () => (
5756
<AdminGuesser
58-
entrypoint={entrypoint}
5957
dataProvider={dataProvider}
6058
schemaAnalyzer={schemaAnalyzer}
6159
>
@@ -109,11 +107,9 @@ export const BooksList = props => (
109107

110108
#### ListGuesser Props
111109

112-
| Name | Type | Value | required | Description |
113-
|----------|------------------|-------|----------|-----------------------------------------|
114-
| children | node or function | - | no | - |
115-
| resource | string | - | yes | endpoint of the resource |
116-
| filters | element | - | no | filters that can be applied to the list |
110+
| Name | Type | Value | required | Description |
111+
|----------|---------|-------|----------|-----------------------------------------|
112+
| filters | element | - | no | filters that can be applied to the list |
117113

118114
You can also use props accepted by React Admin [List](https://marmelab.com/react-admin/List.html).
119115

@@ -139,12 +135,7 @@ export const BooksCreate = props => (
139135

140136
#### CreateGuesser Props
141137

142-
| Name | Type | Value | required | Description |
143-
|----------|------------------|-------|----------|--------------------------|
144-
| children | node or function | - | no | - |
145-
| resource | string | - | yes | endpoint of the resource |
146-
147-
You can also use props accepted by React Admin [Create](https://marmelab.com/react-admin/CreateEdit.html).
138+
You can use props accepted by React Admin [Create](https://marmelab.com/react-admin/CreateEdit.html).
148139

149140
### EditGuesser
150141

@@ -168,12 +159,7 @@ export const BooksEdit = props => (
168159

169160
#### EditGuesser Props
170161

171-
| Name | Type | Value | required | Description |
172-
|----------|------------------|-------|----------|--------------------------|
173-
| children | node or function | - | no | - |
174-
| resource | string | - | yes | endpoint of the resource |
175-
176-
You can also use props accepted by React Admin [Edit](https://marmelab.com/react-admin/CreateEdit.html).
162+
You can use props accepted by React Admin [Edit](https://marmelab.com/react-admin/CreateEdit.html).
177163

178164
### ShowGuesser
179165

@@ -196,12 +182,7 @@ export const BooksShow = props => (
196182

197183
#### ShowGuesser Props
198184

199-
| Name | Type | Value | required | Description |
200-
|----------|------------------|-------|----------|--------------------------|
201-
| children | node or function | - | no | - |
202-
| resource | string | - | yes | endpoint of the resource |
203-
204-
You can also use props accepted by React Admin [Show component](https://marmelab.com/react-admin/Show.html).
185+
You can use props accepted by React Admin [Show component](https://marmelab.com/react-admin/Show.html).
205186

206187
## Hydra
207188

@@ -230,23 +211,74 @@ export default App;
230211

231212
#### HydraAdmin Props
232213

233-
| Name | Type | Value | required | Description |
234-
|------------|----------------|-------|----------|------------------------------|
235-
| entrypoint | string | - | yes | entrypoint of the API |
236-
| mercure | boolean|object | * | yes | configuration to use Mercure |
214+
| Name | Type | Value | required | Description |
215+
|--------------|---------------------|--------------|----------|------------------------------|
216+
| entrypoint | string | - | yes | entrypoint of the API |
217+
| mercure | object&#124;boolean | * | no | configuration to use Mercure |
218+
| dataProvider | object | dataProvider | no | hydra data provider to use |
219+
220+
\* `false` to explicitly disable, `true` to enable with default parameters or an object with the following properties:
221+
- `hub`: the URL to your Mercure hub
222+
- `jwt`: a subscriber JWT to access your Mercure hub
223+
- `topicUrl`: the topic URL of your resources
224+
225+
### Hydra Data Provider
226+
227+
Based on React Admin `create`, `delete`, `getList`, `getManyReference`, `getOne`, `update` methods, the `dataProvider` is used by API Platform Admin to communicate with the API.
228+
In addition, the specific `introspect` method parses your API documentation.
229+
Note that the `dataProvider` can be overridden to fit your API needs.
230+
231+
### Hydra Schema Analyzer
232+
233+
Analyses your resources and retrieves their types according to the [Schema.org](https://schema.org) vocabulary.
234+
235+
## OpenAPI
236+
237+
### OpenApiAdmin
238+
239+
Creates a complete Admin, as [AdminGuesser](components.md#adminguesser), but configured specially for [OpenAPI](https://www.openapis.org/).
240+
If you want to use other formats (see supported formats: `@api-platform/api-doc-parser`) use [AdminGuesser](components.md#adminguesser) instead.
241+
242+
```javascript
243+
// App.js
244+
import { OpenApiAdmin, ResourceGuesser } from "@api-platform/admin";
245+
246+
const App = () => (
247+
<OpenApiAdmin
248+
entrypoint={entrypoint}
249+
docEntrypoint={docEntrypoint}
250+
dataProvider={dataProvider}
251+
authProvider={authProvider}
252+
>
253+
<ResourceGuesser name="books" />
254+
{ /* ... */ }
255+
</OpenApiAdmin>
256+
);
257+
258+
export default App;
259+
```
260+
261+
#### OpenApiAdmin Props
262+
263+
| Name | Type | Value | required | Description |
264+
|---------------|---------------------|-------|----------|------------------------------|
265+
| dataProvider | dataProvider | - | yes | data provider to use |
266+
| docEntrypoint | string | - | yes | doc entrypoint of the API |
267+
| entrypoint | string | - | yes | entrypoint of the API |
268+
| mercure | object&#124;boolean | * | no | configuration to use Mercure |
237269

238270
\* `false` to explicitly disable, `true` to enable with default parameters or an object with the following properties:
239271
- `hub`: the URL to your Mercure hub
240272
- `jwt`: a subscriber JWT to access your Mercure hub
241273
- `topicUrl`: the topic URL of your resources
242274

243-
### Data Provider
275+
### Open API Data Provider
244276

245277
Based on React Admin `create`, `delete`, `getList`, `getManyReference`, `getOne`, `update` methods, the `dataProvider` is used by API Platform Admin to communicate with the API.
246278
In addition, the specific `introspect` method parses your API documentation.
247279
Note that the `dataProvider` can be overridden to fit your API needs.
248280

249-
### Schema Analyzer
281+
### Open API Schema Analyzer
250282

251283
Analyses your resources and retrieves their types according to the [Schema.org](https://schema.org) vocabulary.
252284

@@ -274,9 +306,9 @@ export const BooksShow = props => (
274306

275307
#### FieldGuesser Props
276308

277-
| Name | Type | Value | required | Description |
278-
|--------|--------|-------|----------|--------------------------|
279-
| source | string | - | yes | endpoint of the resource |
309+
| Name | Type | Value | required | Description |
310+
|--------|--------|-------|----------|--------------------------------------|
311+
| source | string | - | yes | name of the property of the resource |
280312

281313
You can also use props accepted by React Admin [basic fields](https://marmelab.com/react-admin/Fields.html#basic-fields).
282314

@@ -286,6 +318,6 @@ Uses React Admin [input components](https://marmelab.com/react-admin/Inputs.html
286318

287319
#### InputGuesser Props
288320

289-
| Name | Type | Value | required | Description |
290-
|--------|--------|-------|----------|--------------------------|
291-
| source | string | - | yes | endpoint of the resource |
321+
| Name | Type | Value | required | Description |
322+
|--------|--------|-------|----------|--------------------------------------|
323+
| source | string | - | yes | name of the property of the resource |

‎admin/customizing.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,10 @@ To do so, you can use the React components provided by API Platform Admin itself
66

77
## Customizing the Admin's Main Page and the Resource List
88

9-
By default, API Platform Admin automatically builds a tailored [Resource component](https://marmelab.com/react-admin/Resource.html) (and all its appropriate children) for each resource type exposed by a web API.
10-
Under the hood it uses the `@api-platform/api-doc-parser` library to parse the API documentation. The API documentation can use Hydra, OpenAPI and any other format supported by the library.
9+
By default, API Platform Admin automatically builds a tailored [Resource component](https://marmelab.com/react-admin/Resource.html)
10+
(and all its appropriate children) for each resource type exposed by a web API.
11+
Under the hood it uses the `@api-platform/api-doc-parser` library to parse the API documentation.
12+
The API documentation can use Hydra, OpenAPI and any other format supported by the library.
1113
Resources are listed in the order they appear in the machine-readable documentation.
1214

1315
However, it's also possible to display only specific resources, and to order them, while still benefiting from all discovery features provided by API Platform Admin.

‎admin/handling-relations.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,10 @@ const dataProvider = hydraDataProvider({
3232
});
3333

3434
export default () => (
35-
<HydraAdmin
36-
dataProvider={dataProvider}
37-
entrypoint={entrypoint}
38-
/>
35+
<HydraAdmin
36+
dataProvider={dataProvider}
37+
entrypoint={entrypoint}
38+
/>
3939
);
4040
```
4141

‎admin/index.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22

33
![Screencast](images/admin-demo.gif)
44

5-
API Platform Admin is a tool to automatically create a beautiful and fully featured administration interface
6-
for any API supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/) or other API specification formats supported by [`@api-platform/api-doc-parser`](https://github.com/api-platform/api-doc-parser) (experimental support for [OpenAPI](https://www.openapis.org/) is also available).
5+
API Platform Admin is a tool to automatically create a beautiful (Material Design) and fully-featured administration interface
6+
for any API supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/), exposing an [OpenAPI documentation](https://www.openapis.org/)
7+
or other API specification formats supported by [`@api-platform/api-doc-parser`](https://github.com/api-platform/api-doc-parser).
78

89
API Platform Admin is the perfect companion of APIs created
9-
using [the API Platform framework](https://api-platform.com), but also supports APIs written with any other programming language or framework as long as they expose a standard Hydra API documentation.
10+
using [the API Platform framework](https://api-platform.com), but also supports APIs written with any other programming language or framework as long as they expose a standard Hydra API documentation or an OpenAPI documentation.
1011

1112
API Platform Admin is a 100% standalone Single-Page-Application written in TypeScript with no coupling to the server part,
1213
according to the API-first paradigm.
@@ -18,15 +19,16 @@ You can **customize everything** by using provided React Admin and [MUI](https:/
1819

1920
## Features
2021

21-
* Automatically generates an admin interface for all the resources of the API thanks to hypermedia features of Hydra
22+
* Automatically generates an admin interface for all the resources of the API thanks to the hypermedia features of Hydra or to the OpenAPI documentation
2223
* Generates 'list', 'create', 'show', and 'edit' screens, as well as a delete button
2324
* Generates suitable inputs and fields according to the API doc (e.g. number HTML input for numbers, checkbox for booleans, selectbox for relationships...)
2425
* Generates suitable inputs and fields according to Schema.org types if available (e.g. email field for `http://schema.org/email`)
2526
* Handles relationships
2627
* Supports pagination
2728
* Supports filters and ordering
2829
* Automatically validates whether a field is mandatory client-side according to the API description
29-
* Sends proper HTTP requests to the API and decodes them using Hydra and JSON-LD formats
30+
* Sends proper HTTP requests to the API and decodes them using Hydra and JSON-LD formats if available
3031
* Nicely displays server-side errors (e.g. advanced validation)
3132
* Supports real-time updates with [Mercure](https://mercure.rocks)
33+
* All the [features provided by React-admin](https://marmelab.com/react-admin/Tutorial.html) can also be used
3234
* **100% customizable**

‎admin/openapi.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# OpenAPI
2+
3+
API Platform Admin has a native support for API exposing an [OpenAPI documentation](https://www.openapis.org/).
4+
5+
To use it, use the `OpenApiAdmin` component, with the entrypoint of the API and the entrypoint of the OpenAPI documentation in JSON:
6+
7+
```javascript
8+
import { OpenApiAdmin } from "@api-platform/admin";
9+
10+
export default () => (
11+
<OpenApiAdmin entrypoint="https://demo.api-platform.com" docEntrypoint="https://demo.api-platform.com/docs.json" />
12+
);
13+
```
14+
15+
**Note:** The OpenAPI documentation needs to follow some assumptions in order to be understood correctly by the underlying `api-doc-parser`.
16+
See the [dedicated part in the `api-doc-parser` library README](https://github.com/api-platform/api-doc-parser#openapi-support).
17+
18+
## Data Provider
19+
20+
By default, the component will use a very basic data provider, without pagination support.
21+
22+
If you want to use [another data provider](https://marmelab.com/react-admin/DataProviderList.html), pass the `dataProvider` prop to the component:
23+
24+
```javascript
25+
import { OpenApiAdmin } from "@api-platform/admin";
26+
import drfProvider from "ra-data-django-rest-framework";
27+
28+
export default () => (
29+
<OpenApiAdmin
30+
dataProvider={drfProvider("https://django-api.com")}
31+
entrypoint="https://django-api.com"
32+
docEntrypoint="https://django-api.com/docs.json"
33+
/>
34+
);
35+
```
36+
37+
## Mercure Support
38+
39+
Mercure support can be enabled manually by giving the `mercure` prop to the `OpenApiAdmin` component.
40+
41+
See also [the dedicated section](real-time-mercure.md).

‎admin/real-time-mercure.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,19 @@ Updates are received by using the `useMercureSubscription` hook in the `ListGues
66

77
To enable Mercure server-side, see the [related documentation](../core/mercure.md).
88

9-
Once enabled, API Platform Admin will automatically detect that Mercure is enabled and will discover the Mercure hub URL by itself.
9+
Once enabled, API Platform Admin for Hydra will automatically detect that Mercure is enabled and will discover the Mercure hub URL by itself.
1010

1111
## Advanced Configuration
1212

13-
If you want to customize the default Mercure configuration, you can either do it with a prop in the `<HydraAdmin>` component:
13+
If you want to customize the default Mercure configuration, you can either do it with a prop in the `<HydraAdmin>` or `<OpenApiAdmin>` component:
1414

1515
```javascript
16-
import { HydraAdmin } from "@api-platform/admin";
16+
import { OpenApiAdmin } from "@api-platform/admin";
1717

1818
export default () => (
19-
<HydraAdmin
19+
<OpenApiAdmin
2020
entrypoint="https://demo.api-platform.com"
21+
docEntrypoint="https://demo.api-platform.com/docs.json"
2122
mercure={{ hub: "https://mercure.rocks/hub" }}
2223
/>
2324
);

‎outline.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ chapters:
6666
- index
6767
- getting-started
6868
- handling-relations
69+
- openapi
6970
- schema.org
7071
- validation
7172
- real-time-mercure

0 commit comments

Comments
 (0)