owncloud / owncloud/docs.owncloud.com
New home and embedding for the libre-graph-api (swagger-ui)
Nobody has claimed this yet.
- Dominant language
- Shell
- Stars
- 0
- Forks
- 2
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 37
Description
While migrating the dev docs to antora, the swagger-ui for the libre-graph-api is one element that needs to be coverd.
The current API definition is located in repo: https://github.com/owncloud/libre-graph-api which provides a subfolder that has been added to owncloud.dev (https://owncloud.dev/libre-graph-api). Because owncloud.dev is techincally dead and the migration is in progess, the libre-graph-api needs migration too.
One idea for the migration is, to use the Antora Swagger UI Extension from opendevise (who's maintainer is the head of the Antora development).
With the extension, we can use the collector extension to download the source from remote and handle it as it would be already saved in the attachment folder.
These are the locations in the ocis dev docs where libre-graph-api is mentioned:
grep -rl libre-graph-api
pages/apis/http/graph/spaces.adoc
pages/apis/http/graph/role.adoc
pages/apis/http/graph/permissions.adoc
pages/apis/http/graph/index.adoc
pages/ocis/adr/0022-sharing-and-space-management-api.adoc
pages/ocis/adr/0007-api-for-spaces.adoc
pages/ocis/adr/0023-index-and-store-metadata.adoc
pages/services/s-list/groups/index.adoc
pages/services/s-list/graph/index.adoc
This needs a lot of testing and checking, but if that works, it would not break the sourcing repo of the libre-graph-api...
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Antora migration setup and run the listed grep command to inspect references in pages/apis/http/graph and the listed ADR and service pages. Evaluate the Antora Swagger UI Extension and collector approach against the existing libre-graph-api source. Done means the Swagger UI is available from the migrated ownCloud docs, all listed references work, and the sourcing repository remains unaffected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, shell
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100