From eaf6ac44e7d38ff6cc71ca72bdaceed59b86c550 Mon Sep 17 00:00:00 2001 From: HampusM Date: Wed, 4 Aug 2021 16:11:10 +0200 Subject: Added API documentation & updated the Typedoc theme dependency --- documentation/API/introduction.md | 3 + documentation/API/v1/repos.md | 165 ++++++++++++++++++++++++++++++++++++++ documentation/API/v1/v1.md | 22 +++++ package.json | 2 +- typedoc.json | 21 ++++- yarn.lock | 8 +- 6 files changed, 215 insertions(+), 6 deletions(-) create mode 100644 documentation/API/introduction.md create mode 100644 documentation/API/v1/repos.md create mode 100644 documentation/API/v1/v1.md diff --git a/documentation/API/introduction.md b/documentation/API/introduction.md new file mode 100644 index 0000000..343bdf6 --- /dev/null +++ b/documentation/API/introduction.md @@ -0,0 +1,3 @@ +Every Githermit instance has a public API. + +These are all the endpoints for this API. \ No newline at end of file diff --git a/documentation/API/v1/repos.md b/documentation/API/v1/repos.md new file mode 100644 index 0000000..483676e --- /dev/null +++ b/documentation/API/v1/repos.md @@ -0,0 +1,165 @@ +## /repos +**Method:** GET + +**Description:**
+Retrieves a list of available repositories. + +**Parameters:**
+None + +**Response:**
+ +| Code | Description | Schema | +|---------|------------------------|---------------------------------------------------------------------| +| 200 | A list of repositories | [\[Repository summary\]](/docs/interfaces/api.RepositorySummary.html) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo +**Method:** GET + +**Description:**
+Retrieves a repository. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|--------------|----------------------------------------------------| +| 200 | A repository | [Repository](/docs/interfaces/api.Repository.html) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/tree +**Method:** GET + +**Description:**
+Retrieves a repository tree. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|------|----------|------------------|----------|--------| +| repo | path | The repository | true | string | +| path | query | Path in the tree | false | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|-------------|---------------------------------------| +| 200 | A tree | [Tree](/docs/modules/api.html#Tree) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/tags +**Method:** GET + +**Description:**
+Retrieves a repository tag. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|-------------|---------------------------------------| +| 200 | A tag | [\[Tag\]](/docs/modules/api.html#Tag) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/log +**Method:** GET + +**Description:**
+Retrieves a repository's log. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|--------------|----------------------------------------------------| +| 200 | A log commit | [\[Log commit\]](/docs/modules/api.html#LogCommit) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/log/:commit +**Method:** GET + +**Description:**
+Retrieves a commit from a repository. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|--------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | +| commit | path | A commit SHA | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|-------------|--------------------------------------------| +| 200 | A commit | [Commit](/docs/interfaces/api.Commit.html) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/branches +**Method:** GET + +**Description:**
+Retrieves a repository's branches. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|--------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|-------------|---------------------------------------------------------------| +| 200 | A branch | [\[Branch summary\]](/docs/interfaces/api.BranchSummary.html) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | + +
+ +## /repos/:repo/branches/:branch +**Method:** GET + +**Description:**
+Retrieves a branch from a repository. + +**Parameters:**
+ +| Name | Location | Description | Required | Schema | +|--------|----------|----------------|----------|--------| +| repo | path | The repository | true | string | +| branch | path | A branch | true | string | + +**Response:**
+ +| Code | Description | Schema | +|---------|-------------|--------------------------------------------| +| 200 | A branch | [Branch](/docs/interfaces/api.Branch.html) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | \ No newline at end of file diff --git a/documentation/API/v1/v1.md b/documentation/API/v1/v1.md new file mode 100644 index 0000000..327d7f2 --- /dev/null +++ b/documentation/API/v1/v1.md @@ -0,0 +1,22 @@ +## About +The first edition of the Githermit API. + +All of following endpoints should be prefixed with `/api/v1`. + +
+ +## /info +**Method:** GET + +**Description:**
+Retrieves information about the Githermit instance. + +**Parameters:**
+None + +**Response:**
+ +| Code | Description | Schema | +|---------|----------------------|---------------------------------------| +| 200 | Instance information | [Info](/docs/modules/api.html#Info) | +| 400-599 | An error | [Error](/docs/modules/api.html#Error) | \ No newline at end of file diff --git a/package.json b/package.json index 21b585c..7f90efb 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,7 @@ "ts-jest": "^27.0.3", "typedoc": "^0.21.5", "typedoc-plugin-pages": "^1.1.0", - "typedoc-theme-slick-dark": "^1.0.2", + "typedoc-theme-slick-dark": "^1.0.4", "typescript": "^4.3.5" } } diff --git a/typedoc.json b/typedoc.json index caaab57..20b8c94 100644 --- a/typedoc.json +++ b/typedoc.json @@ -7,7 +7,7 @@ "hideGenerator": true, "out": "docs", "tsconfig": "packages/server/tsconfig.json", - "theme": "../typedoc-theme-slick-dark/bin/default", + "theme": "node_modules/typedoc-theme-slick-dark/bin/default", "highlightTheme": "dark-plus", "pages": { "reflectionNavigationTitle": "Development", @@ -24,6 +24,25 @@ "source": "documentation/hacking.md" } ] + }, + { + "title": "API", + "pages": [ + { + "title": "Introduction", + "source": "documentation/API/introduction.md" + }, + { + "title": "v1", + "source": "documentation/API/v1/v1.md", + "children": [ + { + "title": "Repos", + "source":"documentation/API/v1/repos.md" + } + ] + } + ] } ] } diff --git a/yarn.lock b/yarn.lock index 7507cd5..d8825ce 100644 --- a/yarn.lock +++ b/yarn.lock @@ -10546,10 +10546,10 @@ typedoc-plugin-pages@^1.1.0: compare-versions "^3.6.0" typedoc-default-themes "^0.10.1" -typedoc-theme-slick-dark@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/typedoc-theme-slick-dark/-/typedoc-theme-slick-dark-1.0.2.tgz#dada20958adafb351b8859737b5c900a4383f33c" - integrity sha512-Vo6EYbPpOJtG/WmkThnnqrj+hBOyx3S6nU5mdLL9uVCrpIHfGRBgHyTveJBzzETGRLuyEf8potjHtlyBF1FkRw== +typedoc-theme-slick-dark@^1.0.4: + version "1.0.4" + resolved "https://registry.yarnpkg.com/typedoc-theme-slick-dark/-/typedoc-theme-slick-dark-1.0.4.tgz#88aaa38f36cb220385c53901ce9e9541d4d5ba3b" + integrity sha512-lE0VjTi3nu0HTNRJTAmUmGB7ih3QSgaPpciBRtfj5XZRb2lii7REeFhmogXhXQd4Ou4vbgs+4PL77O8apmDnFw== typedoc@^0.21.5: version "0.21.5" -- cgit v1.2.3-18-g5258