guibranco / guibranco/gstraccini-bot-api

The API should have an endpoint to list commands in markdown and HTML format.

Open
#7 6 comments 1 reaction 0 assignees View on GitHub
👷🏼 infrastructure 🕓 medium effort enhancement gitauto 🧪 tests
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.