owncloud / owncloud/docs.owncloud.com

New home and embedding for the libre-graph-api (swagger-ui)

Open
#123 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

HOT OCIS Devdocs
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

Open the contributing guide

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.