guibranco / guibranco/gstraccini-bot-api
The API should have an endpoint to list commands in markdown and HTML format.
- Dominant language
- Shell
- Stars
- 1
- Forks
- 0
- Avg merge
- 1m
- Merged PRs (30d)
- 1
Description
### Description
The API should provide an endpoint that allows users to retrieve a list of available commands in two formats:
- **Markdown**: For easier integration with documentation and markdown-based platforms.
- **HTML**: To enable seamless embedding within web applications and other HTML-based platforms.
### Rationale
1. **Consistency**: Having a dedicated endpoint for listing commands ensures that the documentation can be programmatically generated and updated as new commands are introduced.
2. **Ease of Integration**: Markdown and HTML are widely used formats, making it easier to embed or display commands in various platforms such as GitHub, websites, or help docs.
3. **Developer Experience**: Providing this endpoint enhances the developer experience by allowing access to up-to-date command documentation directly from the API.
### Expected Behavior
1. A new endpoint, such as `/commands`, returns a list of commands in the requested format (`markdown` or `html`).
2. The response should include:
- Command name
- Command description
- Parameters (if applicable)
- Examples (if available)
### API Example
```http
GET /commands?format=markdown
```
### Sample Responses
#### Markdown Format
```markdown
## Available Commands
### /start
- **Description**: Initializes the process.
- **Parameters**: None
### /stop
- **Description**: Stops the current process.
- **Parameters**: `force` (optional): boolean, whether to force stop.
```
#### HTML Format
```html
Available Commands
/start
Description: Initializes the process.
Parameters: None
/stop
Description: Stops the current process.
Parameters: force (optional): boolean, whether to force stop.
```
### Additional Notes
- Consider adding versioning support to the endpoint to provide different command lists for various API versions.
- The command descriptions should be regularly updated to reflect any changes in behavior or usage.
- The API code should be written in plain PHP.
Contributor guide
Assessment
This issue has not been assessed yet.