jambonz / jambonz/jambonz-api-server

Swagger docs inaccurate / outdated

Open
#61 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug documentation question
Dominant language
JavaScript
Stars
24
Forks
38
Avg merge
8h 34m
Merged PRs (30d)
1

Description

Something the webapp refresh has illuminated is that the Swagger docs for the API server have quite a bit of inaccuracies compared to actual DTO responses received on the client as well as at least one endpoint missing from the documentation entirely. It would be worth combing over the Swagger yaml and getting the documentation up to date. This issue may overlap with this one: https://github.com/jambonz/jambonz-api-server/issues/13 and we might be able to consolidate and close the older issue 🤔.

**Todo for this issue:**

- [ ] Create a "completed", comprehensive list of what is known to be missing or inaccurate in the Swagger docs

**Comprehensive (incomplete) list of what is missing/inaccurate in Swagger docs:**

- [ ] The API for `Accounts/:account_sid/Applications` is in use for the webapp but missing entirely from the docs
- [ ] The `SmppGateways/SipGateways` show `inbound/outbound` as boolean but they are actually binary: `1/0`
- [ ] The `SpeechCredential` shows `use_for_tts/use_for_stt` as boolean but they are also binary: `1/0`
- [ ] The `RecentCalls` shows the field as `sip_call_id` but it is actually `sip_callid` as returned from the API
- [ ] The :GET `RecentCall` and `RecentCall` pcap toggles have the same ID and both toggle open at the same time
- [ ] The paged responses for CDRs (RecentCalls, Alerts) have a different response schema where the docs claim a field called `batch` but instead the api returns a `page_size` field. Also the `page` and `page_size` fields are strings whereas the `total` field is a number and ideally they would all 3 be numbers 🤔
- [ ] ...

Contributor guide

No contributing guide indexed for this repository

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

Start by locating the Swagger YAML for the API server and compare its schemas and endpoints with the DTO responses used by the webapp. Check each listed discrepancy, including Applications, binary fields, RecentCalls naming and toggles, and paged CDR responses, then identify any additional mismatches. Done means documenting the complete discrepancy list and updating Swagger to match the actual API responses.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.