diff --git a/doc/01_Installation.md b/doc/00_Installation.md similarity index 100% rename from doc/01_Installation.md rename to doc/00_Installation.md diff --git a/doc/10_Extending_Studio/01_Endpoints.md b/doc/10_Extending_Studio/01_Endpoints.md new file mode 100644 index 000000000..566c55b23 --- /dev/null +++ b/doc/10_Extending_Studio/01_Endpoints.md @@ -0,0 +1,108 @@ +# Extending Endpoints + +To add a custom endpoint to the Pimcore Studio Backend you need to implement it like the following: + +- Extend from AbstractApiController + - The AbstractApiController includes the base `API_PATH` and a standard way to serialize your response to json. + - Keep in mind that for serialization the symfony serializer is used and the response must be representable in json if you want to use the standard function. +- Add the route attribute like in a standard symfony way +- For security checks you can use the IsGranted attribute + - This will invoke the according symfony voter and checks the current logged in user for the given permission + - If the user does not have the permission a 403 response is returned +- Add the OpenApi method according to your route + - In order that your endpoint shows up in the OpenApi documentation you need to add the OpenApi method + - If your route specifies that it is a `POST` route use the according OpenApi method `OpenApi\Attributes\Post` +- Add the necessary OpenApi attributes + - Add at least one response, you can checkout the existing responses here: -- TODO ADD PAGE WITH RESPONSES -- + - You can also add some DefaultResponses + - Add query params or request payload if necessary. You can checkout the existing parameters here: -- TODO ADD PAGE WITH PARAMETERS -- + - If you need specific parameters, payloads or responses you can extend OpenApi Schemas, Properties, Responses, etc. + - How to extend OpenApi Schemas, Properties, Responses, etc. is described here: -- TODO ADD PAGE WITH EXTENDING OPENAPI -- +- Implement your endpoint logic in the standard symfony way + - We try to leverage symfony functionality as much as possible for parameters with `#[MapQueryString]` or `#[MapRequestPayload]` attributes + +### Example +```php +value)] + #[Get( + path: self::API_PATH . '/notes', + operationId: 'note_get_collection', + description: 'note_get_collection_description', + summary: 'note_get_collection_summary', + tags: [Tags::Notes->name] + )] + #[PageParameter] + #[PageSizeParameter(50)] + #[NoteSortByParameter] + #[SortOrderParameter] + #[FilterParameter('notes')] + #[FieldFilterParameter] + #[SuccessResponse( + description: 'note_get_collection_success_response', + content: new CollectionJson(new GenericCollection(Note::class)) + )] + #[DefaultResponses([ + HttpResponseCodes::UNAUTHORIZED, + ])] + public function getNotes( + #[MapQueryString] NoteParameters $parameters = new NoteParameters() + ): JsonResponse { + $collection = $this->noteService->listNotes(new NoteElementParameters(), $parameters); + + return $this->getPaginatedCollection( + $this->serializer, + $collection->getItems(), + $collection->getTotalItems() + ); + } +} +``` \ No newline at end of file diff --git a/doc/10_Extending_Studio/README.md b/doc/10_Extending_Studio/README.md new file mode 100644 index 000000000..c77b79157 --- /dev/null +++ b/doc/10_Extending_Studio/README.md @@ -0,0 +1,18 @@ +# Extending Pimcore Studio Backend + +Pimcore Studio Backend Bundle can be extended to add custom endpoints, filters, grid customizations a.m.m. +Most of the customizations can be done by implementing interfaces and registering the services with the according tags. + +The main topics that can be extended are: +- [Endpoints](01_Endpoints.md) +- [Schemes](#Schemas) +- [Filters](#Filters) + - OpenSearch Filters + - Listing Filters +- [Grids](#Grids) + - Columns + - Resolvers + - Collectors +- [Patcher](#Patcher) +- [Updater](#Updater) +- [Additional Attributes](#Additional-Attributes) \ No newline at end of file