Fixing links in marketplace
- Ali González
The page for https://govstack.gitbook.io/bb-emarketplace/8-service-apis is broken. It renders the text while the promise of the swagger files is resolved, then it throws a NextJS Error: Connection Closed with log t promise callback*t
tl;dr: Chapter 8 of emarketplace BB is broken, but only in production. This is probably a clogged DOM issue. We should split the chapter into subchapters to solve it. A consolidation of swagger files will be necessary mid-term, and rules about change management to swagger files should be written on the meta-spec.
General observations about this issue:
Rendering issue only happens on production website. Rendering is correct on Gitbook backoffice
Gitbook backoffice appears to use DOM Lazy loading, supporting theory 1
The spec is referencing 3 different swagger files. They are all exports of a Swagger documentation hosted in SwaggerHub by Beckn. There’s a general issue of having 4 different versions files of the same API (3 on the Gitbook, plus the slightly different SwaggerHub online version).
Theories:
Theory 1: Too many swagger blocks called. There are 74 in a single page (in comparison Payments BB has only 20 swagger blocks). Rendering too many swagger blocks may be clogging the DOM.
Solution: Divide chapter 8 in subchapters.
Pros: It is too long for a normal web browser to render anyways and even when it does, it is too much info on a single webpage for an end-user. Quick to solve.
Cons: Other BB's do not divide chapter 8. However maybe they should, for legibility.
This is the most likely theory
Theory 2: Swagger files referenced are way too large. They contain the full API documentation. In comparison, the Payments BB has one yaml file per endpoint (althought origin / governance is not as clear on these ones, as they don't reference a swaggerhub url). So if this is the problem, and depending on whether the front-end is loading this on-the-fly, it may have trouble generating so many blocks over a large swagger file, so 74 yaml queries to 3 large swagger files, to render each block.
Solution: Break the yml file into many files, one per endpoint.
Pros: Easier to handle changes to the swagger documentation if governance is kept on Gitbook only
Cons: Will decouple what's happening on GitBook and the Swagger app.
Other changes that need to be made about the BB
8.8, 8.10, 8.11 No longer there. They were removed on https://govstack-global.atlassian.net/jira/software/c/projects/MKT/list?selectedIssue=MKT-160 however not much explanation about the removal was done. Should contact Steve Conrad and / or Ravi Prakash
8.13.1 appears twice. Needs to be 8.13.12
The 4 files involved are different, ever so-slightly, and changes made are poorly documented on GitBook. A consolidation of these files will be necessary but will need to talk to Steve Conrad or whoever is the owner to decide on how to go about the consolidation.
The BB is still using the exports from the the swagger app owned by Beck. We may need to own our own swagger tool. See next section
General insights about the Specs procedure
About API documentation:
We should own a platform (swaggerhub, most likely) to manage and handle changes to guiding API’s
We need more control over changes to API procedures. Either we should have a standard procedure to handle exports (resolved vs unresolved) and changes. Or we should point the gitbook swagger blocks to our own GovStack owned swagger instance to avoid duplicity in Gitbook (this would be my preferred way). That would mean the APIs in SwaggerHub would also need to be versioned, mimicking version numbers on GitBook.
Deprecation notices should be specified whenever a numeral goes obsolete and a deprecation change log attached
References
The 4 files involved:
Swaggerhub api documentation: https://app.swaggerhub.com/apis/beckn/e-marketplace-bb/0.2#/