Skip to content

Commit 797ebe1

Browse files
TaubsieTaubsie
authored
Merge pull request #2 from dungeon-hub/develop
API client library and CI stuff
2 parents aa7086b + 3b5070e commit 797ebe1

File tree

8 files changed

+212
-43
lines changed

8 files changed

+212
-43
lines changed

‎.github/workflows/ci.yml

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: "Build and Test"
2+
3+
on:
4+
push:
5+
branches-ignore:
6+
- "main"
7+
- "develop"
8+
- "deployment"
9+
- "preview-deployment"
10+
11+
pull_request:
12+
merge_group:
13+
14+
env:
15+
ARTIFACT: "webHelpDHUB2-all.zip"
16+
DOCKER_VERSION: "243.21565"
17+
INSTANCE: "Writerside/dhub"
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Set up Kotlin
27+
uses: fwilhe2/setup-kotlin@main
28+
29+
- name: Calculate latest Dungeon Hub API version
30+
run: kotlin .github/set-version.main.kts
31+
32+
- uses: JetBrains/writerside-github-action@v4
33+
34+
with:
35+
instance: ${{ env.INSTANCE }}
36+
artifact: ${{ env.ARTIFACT }}
37+
docker-version: ${{ env.DOCKER_VERSION }}
38+
39+
- uses: actions/upload-artifact@v4
40+
41+
with:
42+
name: docs
43+
path: |
44+
artifacts/${{ env.ARTIFACT }}
45+
artifacts/report.json
46+
47+
retention-days: 7
48+
49+
test:
50+
needs: build
51+
runs-on: ubuntu-latest
52+
53+
steps:
54+
- uses: actions/download-artifact@v4
55+
56+
with:
57+
name: docs
58+
path: artifacts
59+
60+
- uses: JetBrains/writerside-checker-action@v1
61+
62+
with:
63+
instance: ${{ env.INSTANCE }}

‎.github/workflows/deploy.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ on:
99

1010
env:
1111
ARTIFACT: "webHelpDHUB2-all.zip"
12-
DOCKER_VERSION: "241.18775"
12+
DOCKER_VERSION: "243.21565"
1313
INSTANCE: "Writerside/dhub"
1414

1515
permissions:
@@ -99,7 +99,7 @@ jobs:
9999
100100
cp -r docs/* .
101101
102-
sudo rm -rf docs Writerside .github .idea .editorconfig .gitignore Dockerfile README.md
102+
sudo rm -rf docs Writerside .github .idea .editorconfig .gitignore Dockerfile README.md ${{ env.ARTIFACT }}
103103
104104
git add .
105105
git commit -am "Automatic deployment"

‎.github/workflows/preview-deploy.yml

+22-2
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,18 @@ on:
99

1010
env:
1111
ARTIFACT: "webHelpDHUB2-all.zip"
12-
DOCKER_VERSION: "241.18775"
12+
DOCKER_VERSION: "243.21565"
1313
INSTANCE: "Writerside/dhub"
1414

1515
permissions:
1616
contents: write
17+
pages: write
1718
id-token: write
1819

20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: false
23+
1924
jobs:
2025
build:
2126
runs-on: ubuntu-latest
@@ -68,6 +73,10 @@ jobs:
6873
needs: test
6974
runs-on: ubuntu-latest
7075

76+
environment:
77+
name: github-pages
78+
url: ${{ steps.deployment.outputs.page_url }}
79+
7180
steps:
7281
- uses: actions/checkout@v4
7382
with:
@@ -99,8 +108,19 @@ jobs:
99108
100109
cp -r docs/* .
101110
102-
sudo rm -rf docs Writerside .github .idea .editorconfig .gitignore Dockerfile README.md
111+
sudo rm -rf docs Writerside .github .idea .editorconfig .gitignore Dockerfile README.md ${{ env.ARTIFACT }}
103112
104113
git add .
105114
git commit -am "Automatic deployment"
106115
git push --force origin preview-deployment
116+
117+
- name: Setup Pages
118+
uses: actions/configure-pages@v5
119+
- name: Upload artifact
120+
uses: actions/upload-pages-artifact@v3
121+
with:
122+
# Upload entire repository
123+
path: '.'
124+
- name: Deploy to GitHub Pages
125+
id: deployment
126+
uses: actions/deploy-pages@v4

‎Writerside/dhub.tree

+1-1
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
</toc-element>
3232
<toc-element topic="User-Commands.md"/>
3333
</toc-element>
34-
<toc-element topic="Dungeon-Hub-API.md">
34+
<toc-element topic="Dungeon-Hub-API.topic">
3535
<toc-element topic="Entities.md">
3636
<toc-element topic="Carry-Type.md"/>
3737
<toc-element topic="Carry-Tier.md"/>

‎Writerside/topics/Dungeon-Hub-API.md

-37
This file was deleted.

‎Writerside/topics/Dungeon-Hub-API.topic

+121
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
3+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
5+
id="Dungeon-Hub-API" title="Dungeon Hub API">
6+
<chapter title="What is the Dungeon Hub API" id="what-is-the-dungeon-hub-api">
7+
<p>The Dungeon Hub API hosts all data that is used in the <a href="Dungeon-Hub-Bot.md"/>. <br/>The <a
8+
href="Dungeon-Hub-Bot.md"/> itself only serves as a client to interact with the API - it does not have
9+
any database access and only persists data through the API. A documentation with all endpoints and their
10+
usage can be found at <a href="https://api.dungeon-hub.net/"/>.</p>
11+
</chapter>
12+
<chapter title="Authentication" id="authentication">
13+
<p>Most endpoints of the Dungeon Hub API require authentication. <br/>The API uses bearer tokens for
14+
authentication, meaning an Authorization header containing the JWT token must be attached
15+
to the request. <br/>The header should look like: <code>Authorization: Bearer &lt;token&gt;</code>. <br/>A
16+
token can be obtained from the authentication server, which is hosted separately to the API
17+
at <a href="https://auth.dungeon-hub.net/"/>.</p>
18+
<chapter title="Logging in as a user" id="logging-in-as-a-user">
19+
<p><code>Coming soon</code></p>
20+
</chapter>
21+
<chapter title="Logging in as a client" id="logging-in-as-a-client">
22+
<warning>
23+
<p>This requires a client to be registered manually. If you're interested in this, please contact <a
24+
href="mailto:[email protected]">the administration</a>.
25+
</p>
26+
</warning>
27+
<p>To log in as a client, you need to send a <code>POST</code> request to
28+
<code>https://auth.dungeon-hub.net/realms/dungeon-hub/protocol/openid-connect/token</code>. <br/>The
29+
request body should be a multipart form containing the following fields:</p>
30+
<list>
31+
<li><code>client_id</code>: <code>dh-server</code></li>
32+
<li><code>grant_type</code>: <code>client_credentials</code></li>
33+
</list>
34+
<p>As the Authorization header, you should use basic authentication with the client's credentials (client id
35+
as username,
36+
client secret as password).</p>
37+
</chapter>
38+
</chapter>
39+
<chapter title="Connecting to the API" id="connecting-to-the-api">
40+
<p>All API endpoints are reachable under <a href="https://api.dungeon-hub.net/"/>. A simple documentation of
41+
all endpoints is available there. <br/>To ease the connection to the API, a Kotlin/JVM library containing
42+
all models that the API uses in requests and responses, as well as a library to send requests to all
43+
possible endpoints is available at <a href="https://github.com/dungeon-hub/dungeon-hub-api"/>.</p>
44+
<chapter title="Importing the client library" id="importing-client">
45+
<tabs>
46+
<tab id="gradle-kotlin-import" title="Gradle (Kotlin)">
47+
<p>First of all, add a dependency to your <code>gradle/libs.versions.toml</code> file.</p>
48+
<p>This file is used to declare the versions of libraries you use in one central place.</p>
49+
50+
<!--suppress WrsCodeBlockWidthInspection -->
51+
<code-block lang="toml">
52+
[versions]
53+
dungeon-hub-api-client = "%client-version%"
54+
55+
[libraries]
56+
dungeon-hub-api-client = {module = "net.dungeon-hub.api:client", version.ref = "dungeon-hub-api-client" }
57+
</code-block>
58+
59+
<p>Then, you can simply add the dependency to your <code>build.gradle.kts</code> file.</p>
60+
61+
<code-block lang="kotlin">
62+
repositories {
63+
// other repositories
64+
65+
mavenCentral()
66+
}
67+
68+
dependencies {
69+
// other dependencies
70+
71+
implementation(libs.dungeon.hub.api.client)
72+
}
73+
</code-block>
74+
</tab>
75+
76+
<tab id="gradle-groovy-import" title="Gradle (Groovy)">
77+
<p>First of all, add a dependency to your <code>gradle/libs.versions.toml</code> file.</p>
78+
<p>This file is used to declare the versions of libraries you use in one central place.</p>
79+
80+
<!--suppress WrsCodeBlockWidthInspection -->
81+
<code-block lang="toml">
82+
[versions]
83+
dungeon-hub-api-client = "%client-version%"
84+
85+
[libraries]
86+
dungeon-hub-api-client = {module = "net.dungeon-hub.api:client", version.ref = "dungeon-hub-api-client" }
87+
</code-block>
88+
89+
<p>Then, you can simply add the dependency to your <code>build.gradle</code> file.</p>
90+
91+
<code-block lang="groovy">
92+
repositories {
93+
// other repositories
94+
95+
mavenCentral()
96+
}
97+
98+
dependencies {
99+
// other dependencies
100+
101+
implementation(libs.dungeon.hub.api.client)
102+
}
103+
</code-block>
104+
</tab>
105+
106+
<tab id="maven-import" title="Maven">
107+
Please add the following to your `pom.xml`:
108+
<code-block lang="xml">
109+
&lt;dependencies&gt;
110+
&lt;dependency&gt;
111+
&lt;groupId&gt;net.dungeon-hub.api&lt;/groupId&gt;
112+
&lt;artifactId&gt;client&lt;/artifactId&gt;
113+
&lt;version&gt;%client-version%&lt;/version&gt;
114+
&lt;/dependency&gt;
115+
&lt;/dependencies&gt;
116+
</code-block>
117+
</tab>
118+
</tabs>
119+
</chapter>
120+
</chapter>
121+
</topic>

‎Writerside/topics/Welcome.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ You can select the topic you want to learn about below.
1313
<a href="Dungeon-Hub-Bot.md"></a>
1414
</li>
1515
<li>
16-
<a href="Dungeon-Hub-API.md"></a>
16+
<a href="Dungeon-Hub-API.topic"></a>
1717
</li>
1818
<li>
1919
<a href="Dungeon-Hub-Website.md"></a>

‎Writerside/v.list

+2
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,6 @@
22
<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
33
<vars>
44
<var name="product" value="Writerside"/>
5+
<var name="model-version" value="{MODEL_VERSION}"/>
6+
<var name="client-version" value="{CLIENT_VERSION}"/>
57
</vars>

0 commit comments

Comments
 (0)