Skip to content

Commit 4e89efa

Browse files
ceviixxceviixx
committed
Initial commit
0 parents  commit 4e89efa

File tree

13 files changed

+3328
-0
lines changed

13 files changed

+3328
-0
lines changed

‎.github/scripts/link_endpoints.sh‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#!/bin/bash
2+
# Usage: ./link_endpoints.sh README.md openapi/openapi.yaml
3+
4+
README="$1"
5+
OPENAPI="$2"
6+
BRANCH="main"
7+
8+
TMP_README="${README}.tmp"
9+
cp "$README" "$TMP_README"
10+
11+
ROUTE_REGEX='^[-*] (GET|POST|PUT|DELETE|PATCH)? ?(\[)?(/[^ ]+):?(\])?(\(openapi/openapi.yaml#L[0-9]+\))?:'
12+
13+
14+
{
15+
while IFS= read -r line; do
16+
if [[ $line =~ \[([^\]]+)\]\(openapi/openapi.yaml#L[0-9]+\) ]]; then
17+
ROUTE="${BASH_REMATCH[1]}"
18+
LINE_NUM=$(grep -n "^[[:space:]]*$ROUTE" "$OPENAPI" | cut -d: -f1 | head -n1)
19+
if [ ! -z "$LINE_NUM" ]; then
20+
METHOD=$(echo "$line" | grep -oE 'GET|POST|PUT|DELETE|PATCH')
21+
echo "- $METHOD [$ROUTE](openapi/openapi.yaml#L$LINE_NUM):"
22+
continue
23+
fi
24+
fi
25+
if [[ $line =~ -[[:space:]]*(GET|POST|PUT|DELETE|PATCH)[[:space:]]+(/[^ ]+): ]]; then
26+
ROUTE="${BASH_REMATCH[2]}:"
27+
LINE_NUM=$(grep -n "^[[:space:]]*$ROUTE" "$OPENAPI" | cut -d: -f1 | head -n1)
28+
if [ ! -z "$LINE_NUM" ]; then
29+
METHOD="${BASH_REMATCH[1]}"
30+
echo "- $METHOD [$ROUTE](openapi/openapi.yaml#L$LINE_NUM):"
31+
continue
32+
fi
33+
fi
34+
echo "$line"
35+
done < "$README"
36+
} > "$TMP_README"
37+
38+
mv "$TMP_README" "$README"
39+
echo "Add links to $README."

‎.github/workflows/deploy-docs.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Deploy
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: '18'
28+
29+
- name: Install dependencies
30+
run: npm install
31+
32+
- name: Lint OpenAPI spec
33+
run: npm run test
34+
35+
- name: Build documentation
36+
run: |
37+
# Create output directory
38+
mkdir -p dist
39+
40+
# Build HTML documentation using Redocly
41+
npx redocly build-docs openapi/openapi.yaml --output=dist/index.html --template=docs/index.html
42+
43+
# Copy any additional assets if needed
44+
if [ -f "docs/favicon.png" ]; then
45+
cp docs/favicon.png dist/
46+
fi
47+
if [ -f "docs/logo-light.svg" ]; then
48+
cp docs/logo-light.svg dist/
49+
fi
50+
51+
- name: Add Umami Tracking Script
52+
run: |
53+
sed -i '/<head>/a <script defer src="https://cloud.umami.is/script.js" data-website-id="f496fea8-5956-4d1e-ae3d-89d5d4fa538f"></script>' dist/index.html
54+
55+
- name: Setup Pages
56+
uses: actions/configure-pages@v4
57+
58+
- name: Upload artifact
59+
uses: actions/upload-pages-artifact@v3
60+
with:
61+
path: './dist'
62+
63+
deploy:
64+
environment:
65+
name: github-pages
66+
url: ${{ steps.deployment.outputs.page_url }}
67+
runs-on: ubuntu-latest
68+
needs: build
69+
steps:
70+
- name: Deploy to GitHub Pages
71+
id: deployment
72+
uses: actions/deploy-pages@v4

‎.github/workflows/link_readme_endpoints.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Readme linker
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
paths:
7+
- 'README.md'
8+
- 'openapi/openapi.yaml'
9+
- '.github/scripts/link_endpoints.sh'
10+
workflow_dispatch:
11+
12+
jobs:
13+
link-endpoints:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout repository
17+
uses: actions/checkout@v3
18+
- name: Set up Git
19+
run: |
20+
git config --global user.name "github-actions[bot]"
21+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
22+
- name: Make script executable
23+
run: chmod +x .github/scripts/link_endpoints.sh
24+
- name: Run link_endpoints.sh
25+
run: ./.github/scripts/link_endpoints.sh README.md openapi/openapi.yaml ceviixx gh-pages-api-test
26+
- name: Commit and push changes
27+
run: |
28+
git add README.md
29+
git commit -m "chore: update README endpoint links [automated]" || echo "No changes to commit"
30+
git push

‎.github/workflows/redocly-lint-pr.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Lint PRs
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
7+
permissions:
8+
contents: read
9+
pull-requests: write
10+
11+
jobs:
12+
redocly-lint:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- name: Setup Node
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
22+
- run: npm install
23+
24+
- name: Lint (Annotations)
25+
id: lint_anno
26+
continue-on-error: true
27+
run: npx redocly lint openapi/openapi.yaml --format=github-actions
28+
29+
- name: Lint (Markdown Report)
30+
id: lint_md
31+
continue-on-error: true
32+
run: npx redocly lint openapi/openapi.yaml --format=markdown > lint-report.md
33+
34+
35+
- name: Clean markdown report
36+
if: ${{ steps.lint_anno.outcome == 'failure' }}
37+
run: sed -n '/^| Severity \| Location \| Problem \| Message \|/,$p' lint-report.md | sed '/^Validation failed$/,$d' > lint-report.clean.md
38+
39+
- name: Build comment body
40+
if: ${{ steps.lint_anno.outcome == 'failure' }}
41+
run: |
42+
{
43+
echo "<!-- redocly-lint -->"
44+
echo "@${{ github.event.pull_request.user.login }} Please fix the issues below and push another commit."
45+
cat lint-report.clean.md
46+
} > lint-comment.md
47+
48+
- name: Add or update PR comment
49+
if: ${{ steps.lint_anno.outcome == 'failure' }}
50+
uses: peter-evans/create-or-update-comment@v4
51+
with:
52+
token: ${{ secrets.GITHUB_TOKEN }}
53+
issue-number: ${{ github.event.pull_request.number }}
54+
body-file: lint-comment.md
55+
edit-mode: replace
56+
find: '<!-- redocly-lint -->'
57+
58+
- name: Fail if Lint-Error
59+
if: ${{ steps.lint_anno.outcome == 'failure' }}
60+
run: exit 1

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
dist
2+
node_modules
3+
package-lock.json
4+
.DS_Store

‎CONTRIBUTING.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Contributing Guide
2+
3+
Thanks for helping improve the **Umami API Docs**! Every contribution that cleans up and completes the OpenAPI spec is welcome. This project aims to provide a clean, community-maintained API reference.
4+
5+
> **Scope:** Please change **only the API spec** (the `openapi/` files). Do **not** modify badges, workflows, website configs, or unrelated files.
6+
7+
---
8+
9+
## What to work on
10+
11+
- **Complete missing or incomplete endpoints.**
12+
- **Add or improve operation/field descriptions.**
13+
Many places are intentionally left with a placeholder like `description: TBD`. Replace these with clear, complete English descriptions. Avoid empty values and placeholders such as `null`, or `-`.
14+
15+
See the **“Endpoints not complete”** section in the root `README.md` — it links directly to the lines that need work.
16+
- **Extend responses** where applicable, especially **`400`** and **`405`** use cases (validation errors, method not allowed), with schemas and examples.
17+
18+
---
19+
20+
## Local setup & validation
21+
22+
1. Install dependencies:
23+
```bash
24+
npm install
25+
```
26+
2. Lint the spec before committing:
27+
```bash
28+
npm run test
29+
```
30+
This runs Redocly lint. The PR will also run this check automatically as a fallback; PRs with lint errors cannot be merged.
31+
32+
> Tip: Keep runs fast by focusing on the files you changed and committing incrementally.
33+
34+
35+
---
36+
37+
## Descriptions (how to write and where to add)
38+
39+
- **Replace placeholders:** Search for `description: x` and replace them with meaningful text. Do not leave `description:` empty and do not use `null` or `TBD`.
40+
- **Level of detail:** One or two short sentences are usually enough. Explain *what* the operation/field is for and any constraints that are not obvious from the schema.
41+
- **Tone & language:** English, concise, and consistent with the rest of the document.
42+
- **Where to add:**
43+
- **Operations:** Under each HTTP method (e.g., `paths./resource.get.description`).
44+
- **Parameters:** Each parameter (`name`, `in`, `required`) should have a `description` explaining format, examples, and semantics.
45+
- **Schemas & properties:** Add `description` to component schemas and their properties where helpful.
46+
- **Validation:** The linter requires descriptions to be strings. Empty or `null` values (e.g., `description:` with nothing after it) will fail the lint check.
47+
48+
49+
---
50+
51+
## Style & structure guidelines
52+
53+
Please follow these conventions to keep the spec consistent:
54+
55+
- **Descriptions:** Must be non-empty, short, and precise. Avoid “TBD” or `null`.
56+
- **Operation IDs:** Use lowerCamelCase and make them unique per operation (e.g., `getWebsiteById`, `listEvents`).
57+
- **Tags:** Prefer existing tags; only add new ones if absolutely necessary.
58+
- **Parameters:** Document `in`, `name`, `required`, and a clear `description`. Provide `schema` with `type/format` and examples.
59+
- **Request bodies:** Include `content: application/json` with a proper `schema` and a minimal `example`.
60+
- **Responses:** Always include `content` with `schema` and at least one example.
61+
- **200 / 201:** Add realistic examples.
62+
- **400 (Bad Request):** Use this for validation errors or bad input.
63+
- **405 (Method Not Allowed):** Add when an HTTP verb is unsupported.
64+
- **Schemas:** Reuse components in `components/schemas` where possible. Prefer `object` with explicit `properties`, `required`, and types.
65+
- **Examples:** Favor small but realistic, redacted data. Avoid secrets or PII.
66+
67+
---
68+
69+
## How to contribute (workflow)
70+
71+
1. **Create a branch** from `main` (e.g., `feat/complete-sessions-properties`).
72+
2. Make focused changes **only in `openapi/`**.
73+
3. Run:
74+
```bash
75+
npm run test
76+
```
77+
Fix any linting errors.
78+
4. **Commit** with a clear message (e.g., `docs(api): add 400/405 and examples for /websites/{id}/active`).
79+
5. **Open a Pull Request**:
80+
- Title: short & descriptive.
81+
- Description: list what you completed (endpoints, responses, examples).
82+
- Link to the items from **“Endpoints not complete”** you addressed.
83+
6. The PR will:
84+
- Run the lint job and annotate problems inline.
85+
- Post a compact lint report comment if issues are found.
86+
- **Block merging** until the lint check passes.
87+
88+
---
89+
90+
## Review checklist (before you submit)
91+
92+
- [ ] Only `openapi/` files changed.
93+
- [ ] All operations/parameters/schemas have non-empty `description` where applicable (placeholders like `description: x` replaced).
94+
- [ ] `200/201` responses include `schema` **and** example(s).
95+
- [ ] Added/validated **`400`** and **`405`** where relevant.
96+
- [ ] No unused components/schemas.
97+
- [ ] `npm run test` passes locally.
98+
99+
---
100+
101+
## Questions
102+
103+
If you’re unsure about structure, examples, or where to add 400/405, open a draft PR or start a discussion. We’d rather help early than request large reworks later. Thanks for contributing!

0 commit comments

Comments
 (0)