Create internal spec for MPC REST API specification

This year we are planning to deprecate our wikimedia server, which includes some specification documents and notes. One of those specs is the marketplace client API specifications, which will need to be imported here to maintain the availability of the documentation. The notes are available on the Marketplace REST page.

added MBO prioritymedium severitynormal statetodo team:webdev labels

assigned to @malowe

Just to make sure we are on the same page, the specs should be public, not internal.

I would like the source fo the spec to be committed in the https://gitlab.eclipse.org/eclipsefdn/it/websites/marketplace.eclipse.org/ repo (private) with the output published on our API spec website: https://webdev.eclipse.org/docs/api/

By internal, I mean internal to the project rather than an external/remote spec. Similar to how we host the "Additional API specs" https://gitlab.eclipse.org/eclipsefdn/it/webdev/eclipsefdn-api-spec-host/-/blob/main/spec/additional-api-docs.yaml?ref_type=heads.

Right now, we don't have it setup to enable Github creds in Jenkins. Would you be comfortable with a 2 phase approach to make sure we don't overcommit or have a period where we don't have the specs available? I'm thinking I migrate the spec here first, and then do some testing to see about fetching protected resources in a timebox to make sure we don't encroach on other deliverables

Would you be comfortable with a 2 phase approach to make sure we don't overcommit or have a period where we don't have the specs available? I'm thinking I migrate the spec here first, and then do some testing to see about fetching protected resources in a timebox to make sure we don't encroach on other deliverables

+1

Looking into this, this won't be able to perfectly replicate the schema as there is a gap in openapi spec for nodes with attributes and a basic value like <iu selected="TRUE">org.zeroturnaround.eclipse.feature</iu>. You can have attributes and nested objects, but you can't add attributes to basic value nodes in OAS, including in latest.

There is an issue open for this since 2016 and there is some minor movement on the issue, but nothing solid. As a workaround I'll add a note to the description of the element to note that it will have a text value and give a sample.

mentioned in commit e8b1577e

mentioned in merge request !8 (merged)

Do we want to document non 200 responses? Right now there is no documentation of error states, and I don't know what those states are/will be after the upgrade.

We should but the priority for phase 1 is to migrate the existing documentation. I suggest we create sub-issues to track what we think is missing unless you can easily add them with the work you are doing.

added #9 (closed) as child task

added #10 as child task

mentioned in commit 570dda1f

added statereview label and removed statetodo label

mentioned in commit 37c29c71

mentioned in commit a5233787

This is now live, with Wiki updated

closed

removed statereview label