Add CustomersDot Marketplace openAPI doc
What does this MR do and why?
For issue https://gitlab.com/gitlab-org/customers-gitlab-com/-/issues/5314+
Background
Several possible options were discussed to achieve the goal of issue https://gitlab.com/gitlab-org/customers-gitlab-com/-/issues/5314+
-
create a new page in Gitlab project
https://gitlab.com/gitlab-org/gitlab
- Pros: this is easy, quick solution
- Cons: it is not natural to have a CustomersDot project api doc inside Gitlab project.
-
create a new repository under
https://gitlab.com/gitlab-org/
.- Pros: it is natural to have a dedicated project to hold CustomersDot public api doc
- Cons: it takes time to choose a good project name, and go through the new repository approval process
-
use 3rd party service https://github.com/Redocly/redoc
- Pros: it seems more powerful (richer feature), comparing to Gitlab.com's openAPI doc support
- Cons: legal/license review, procurement process(if we need to use the paid version)
After evaluating the Pros/Cons for the above options, we think it is better to iterate from option 1 as MVC.
This MR:
- create a new folder/document
cdot_marketplace/openapi.yaml
underdoc/api/openapi/
. So the new document isdoc/api/openapi/cdot_marketplace/openapi.yaml
- the new document content is a simple extract of the Marketplace APIs from existing CustomersDot openAPI doc
Note:
- the
try it out
feature does not work (the same as https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/main/doc/api/openapi.yaml). - this page is NOT contained in https://docs.gitlab.com/. There is another MR Add Marketplace API overview page (!109619 - merged) to add the CDot marketplace openAPI overview page in https://docs.gitlab.com/, and then it has a link to this page. Finally, it is expected to present similarly as the Gitlab openAPI overview.
Screenshots or screen recordings
Screenshots are required for UI changes, and strongly recommended for all other merge requests.
How to set up and validate locally
Please review the openAPI page rendered at: https://gitlab.com/gitlab-org/gitlab/-/blob/qzhao-cdot-5314-add-cdot-marketplace-openapi-doc/doc/api/openapi/cdot_marketplace/openapi.yaml
You can compare with the https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/main/doc/api/openapi.yaml. It should be consistent (as the contents are copy/paste from there)
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.