slack-ruby / slack-ruby/slack-api-ref

Fix JSON of Slack sample responses

Open
#17 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

new feature
Dominant language
Ruby
Stars
43
Forks
14
PR merge metrics
No merged PRs in 30d

Description

The sample responses from the official Slack documentation are often invalid JSON.
For example, check files.upload (because of '...') or im.history (because of a trailing comma in the second message).

Given that slackhq/slack-api-docs is currently not receiving any updates, we should fix that on our side.

I was looking into possible solutions. Unfortunately I did not find any pure-Ruby solution yet. Do you know of any? JSON is tricky to fix automatically. The two most promising solutions I found are:

Both projects promise automatic fixing of JSON.
Since eslint/eslint is well-maintained and offers lots of fixes, I would go with that.

Heads up:

  • Javascript Runtime required.
  • eslint fixes files in-place. We would need to call it from the commandline.

Here is an example of how I would integrate it. I'm not really happy about the code but I couldn't come up with anything better either.

If you like the idea then I would go ahead and integrate it.
Otherwise I'm open for suggestions.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the files.upload and im.history examples linked in the issue to identify the invalid JSON cases. Review the linked eslintfix.rb integration example and the available Ruby and JavaScript options before choosing an approach. Done means the affected Slack sample responses are valid JSON without requiring undocumented changes to the upstream Slack documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
eslint, javascript, ruby
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.