-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
e864182
commit ca29913
Showing
2 changed files
with
63 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -44,8 +44,6 @@ Add the `x-feedbackLink` property under the `info` section and paste in your fee | |
Here’s an example of what this might look like in your OpenAPI YAML file: | ||
|
||
```yaml | ||
# openapi.yaml | ||
|
||
openapi: 3.1.0 | ||
info: | ||
title: Your Amazing API | ||
|
@@ -68,6 +66,69 @@ Now, go to your API documentation on Bump.sh to confirm the feedback form is emb | |
|
||
When you click that the form you set up should appear. Then you can send a test submission, to make sure it works as expected. When you do this it's best to do it in a private window to flush out any odd permissions issues, because you want to emulate an end-user, and they won't be logged in to the form builder software either. | ||
|
||
## Alternative Idea: GitHub Issues as Feedback | ||
|
||
If you're using GitHub, and the audience using the API have access to this repository, you might want to consider using [GitHub Issue Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) instead of a custom form on one of these other services. | ||
|
||
GitHub has it's own form builder which you can use to create something very similar. | ||
|
||
 | ||
|
||
Create a new file `.github/ISSUE_TEMPLATE/feedback.yaml`, and use this example to start you off: | ||
|
||
```yaml | ||
name: Feedback | ||
description: Help us improve this API with constructive feedback. | ||
title: "[Feedback]: " | ||
labels: ["feedback"] | ||
assignees: | ||
- philsturgeon # change this to whoever should be in charge of handling feedback | ||
body: | ||
- type: markdown | ||
attributes: | ||
value: | | ||
Thanks for taking the time to help us improve! | ||
- type: textarea | ||
id: doing-well | ||
attributes: | ||
label: What are we doing well? | ||
description: Help us know where energy has been well invested so we can keep that up. | ||
validations: | ||
required: true | ||
- type: textarea | ||
id: could-improve | ||
attributes: | ||
label: What would you like to see improved? | ||
description: Help us learn what you'd like to see done better so we can make life easier for more users. | ||
validations: | ||
required: true | ||
- type: input | ||
id: contact | ||
attributes: | ||
label: Contact Details | ||
description: How can we get in touch with you if we need more info? | ||
placeholder: "eg: [email protected]" | ||
validations: | ||
required: false | ||
``` | ||
When you have committed that and pushed it to your default branch (probably `main`), you can go to **GitHub** > **Issues** > **New**, and the **Feedback** option should have appeared. | ||
|
||
Copy this URL out of your browsers' address bar, e.g.: `https://github.com/bump-sh-examples/train-travel-api/issues/new/choose`. Paste that URL into `x-feedbackLink.url`: | ||
|
||
```yaml | ||
openapi: 3.1.0 | ||
info: | ||
title: Your Amazing API | ||
version: 1.0.0 | ||
description: "API documentation with integrated feedback form" | ||
x-feedbackLink: | ||
label: Give feedback | ||
url: "https://github.com/bump-sh-examples/train-travel-api/issues/new/choose" | ||
``` | ||
|
||
That's it! | ||
|
||
## Tips for Effective Feedback Collection | ||
|
||
**Keep it short and focused** | ||
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.