Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ability to describe custom actions using Attribute #15

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

MarcEspiard
Copy link

Description

This is a very basic attempt to support custom actions (or default actions that are not coming from a Trait) through adding an Attribute to the controller method you want to appear in the output.
The attribute takes decriptor class strings as arguments, which allows users full control of the output for the endpoint.

To note:

  • I had to increase the PHP version requirement to >8.0 so I could use attributes. As it's a breaking change, it could be a good idea to increase it to >8.1 right now so Enums could be used in future development without another breaking change.
  • I did not implement a way to supply a custom schema as you can completely overwrite the action output using your own action descriptor if you wish to do so
  • the change in src/Builders/Paths/Operation/SchemaBuilder.php is a bit hacky, if the custom action is not one of the default actions (store, update, show etc..) it would just exit. The change makes it so it assumes you want the default schema for that controller. There is definitely a better way to handle this but limited by time here.
  • I did not yet write documentation for this feature, I would like to discuss the PR and approach first to make sure it's accepted, I'll definitely document how to use it if the PR is OK to merge

Motivation and context

In our case, we reimplemented the Users > store action as our app needs to invite users on creation and we don't always need to create a user record in our db.
We needed this package to support custom actions so our new Users > store action would be automatically documented.

How has this been tested?

Added a test case and supporting classes.
Have extensively tested locally with our own production app too.

Screenshots (if appropriate)

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

Go over all the following points, and put an x in all the boxes that apply.

Please, please, please, don't send your pull request until all of the boxes are ticked. Once your pull request is created, it will trigger a build on our continuous integration server to make sure your tests and code style pass.

  • I have read the CONTRIBUTING document.
  • My pull request addresses exactly one patch/feature.
  • I have created a branch for this patch/feature.
  • Each individual commit in the pull request is meaningful.
  • I have added tests to cover my changes.
  • If my change requires a change to the documentation, I have updated it accordingly.

If you're unsure about any of these, don't hesitate to ask. We're here to help!

@Rocksheep Rocksheep self-requested a review June 14, 2023 06:52
@Rocksheep
Copy link
Collaborator

The idea of the change is very interesting. Using Attributes can be very useful to add extra descriptions to the API. Our original idea was to hook into the descriptors to add information after it was done creating the documentation, but this might be more interesting.

We don't want to implement both options so I'm going to start a discussion with a couple of coworkers to see which solution fits best. I hope you don't mind the delay!

@Rocksheep Rocksheep removed their request for review June 21, 2023 07:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants