Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions .github/workflows/swagger.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
name: API Swagger Docs

on:
push:
branches:
- main
paths-ignore:
- "docs/swagger.yaml"
pull_request:
paths:
- "api/**/*"
- "scripts/generate-swagger.sh"

jobs:
api-swagger:
name: Generate swagger.yaml
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write

steps:
- uses: actions/checkout@v7

- uses: actions/setup-go@v7
with:
go-version-file: "go.mod"
cache: false

- name: Make swagger.yaml
run: ./scripts/generate-swagger.sh

- name: Publish Artifact
uses: actions/upload-artifact@v7
with:
name: swagger.yaml
path: docs/swagger.yaml

- name: Check if there is a difference
uses: mathiasvr/command-output@v2.0.0
id: diff
with:
run: git diff --no-color docs/swagger.yaml

- name: Mark previous comment as outdated if no diff
if: ${{ github.event_name == 'pull_request' && steps.diff.outputs.stdout == '' }}
uses: marocchino/sticky-pull-request-comment@v3
with:
header: diff
hide: true
hide_classify: "OUTDATED"

- name: Post comment with diff in original PR
if: ${{ github.event_name == 'pull_request' && steps.diff.outputs.stdout }}
uses: marocchino/sticky-pull-request-comment@v3
with:
header: diff
message: |
This PR introduces the following changes in the API documentation:
```diff
${{ steps.diff.outputs.stdout }}
```

- name: Commit and push if stage is outdated
if: ${{ github.event_name == 'push' && steps.diff.outputs.stdout }}
run: |
git config user.name "github-actions"
git config user.email "github-actions@users.noreply.github.com"
git add docs/swagger.yaml
git commit -m "ci: regenerate swagger.yaml after merge"
git push

deploy-pages:
name: Deploy Swagger UI to GitHub Pages
needs: api-swagger
if: github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
concurrency:
group: pages
cancel-in-progress: false

steps:
- uses: actions/checkout@v7

- name: Overwrite docs/swagger.yaml with the freshly generated spec
uses: actions/download-artifact@v4
with:
name: swagger.yaml
path: docs

- uses: actions/configure-pages@v6

- name: Upload docs/ (Swagger UI + spec)
uses: actions/upload-pages-artifact@v3
with:
path: docs

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
35 changes: 35 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# syntax=docker/dockerfile:1

FROM golang:1.26-bookworm AS build

WORKDIR /src

COPY go.mod go.sum ./
RUN go mod download

COPY . .

ARG TARGETOS
ARG TARGETARCH

RUN CGO_ENABLED=0 \
GOOS=${TARGETOS:-linux} \
GOARCH=${TARGETARCH:-amd64} \
go build \
-trimpath \
-ldflags="-s -w" \
-o /out/api \
./cmd/authapi


FROM gcr.io/distroless/static-debian13:nonroot

WORKDIR /app

COPY --from=build --chown=nonroot:nonroot /out/api /app/api

EXPOSE 8080

USER nonroot:nonroot

ENTRYPOINT ["/app/api"]
17 changes: 13 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
.PHONY: run demo clean
.PHONY: demo api swagger-ui clean-demo clean-api

demo: clean-demo
@echo "Building demo image..."
docker build -f docker/Dockerfile.demo -t demo-simpleauthlink .
@echo "Running demo container..."
docker run --name demo-simpleauthlink --env-file demo.env -p ${PORT}:80 -d demo-simpleauthlink
@set -a; . ./.env; set +a; docker run --name demo-simpleauthlink --env-file .env -p $${PORT}:$${PORT} demo-simpleauthlink

clean-demo:
@echo "Cleaning up previous containers and images..."
Expand All @@ -18,12 +18,21 @@ api: clean-api
@echo "Building API image..."
docker build -f docker/Dockerfile.prod -t simpleauthlink .
@echo "Running API container..."
docker run --name simpleauthlink --env-file .env -p ${PORT}:80 simpleauthlink
@set -a; . ./.env; set +a; docker run --name simpleauthlink --env-file .env -p $${PORT}:$${PORT} simpleauthlink

clean-api:
@echo "Cleaning up previous containers and images..."
@docker rm -f simpleauthlink 2>/dev/null || true
@echo "Containers cleaned up"
@docker rmi -f simpleauthlink 2>/dev/null || true
@echo "Images cleaned up"
@echo "Cleaning up done"
@echo "Cleaning up done"

swagger-ui:
./scripts/generate-swagger.sh
@trap 'truncate -s 0 docs/swagger.yaml' EXIT; \
docker run --rm \
-p 8081:8080 \
-e SWAGGER_JSON=/spec/swagger.yaml \
-v "$$PWD/docs:/spec:ro" \
docker.swagger.io/swaggerapi/swagger-ui
61 changes: 53 additions & 8 deletions api/service.go → api/api.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,50 @@
// Package api provides the HTTP API for the SimpleAuth.link service.
//
// @title SimpleAuth.link API
// @version 1.0
// @description Passwordless authentication API for your users using just an email address.
//
// @contact.name API Support
// @contact.url https://simpleauth.link
// @contact.email info@simpleauth.link
//
// @license.name AGPL-3.0
// @license.url https://github.com/SimpleAuthLink/authapi/blob/main/LICENSE
//
// @servers.url https://demo.simpleauth.link
// @servers.description Demo
//
// @servers.url https://api.simpleauth.link
// @servers.description Production
//
// @servers.url {scheme}://{host}
// @servers.description Custom
// @servers.variables.enum scheme https
// @servers.variables.enum scheme http
// @servers.variables.default scheme http
// @servers.variables.default host localhost:8080
//
// @tag.name apps
// @tag.description Create and manage your App
// @tag.docs.url https://docs.simpleauth.link/about/apps
// @tag.docs.description About Apps
//
// @tag.name tokens
// @tag.description Request and verify tokens
// @tag.docs.url https://docs.simpleauth.link/about/tokens
// @tag.docs.description About Tokens
package api

// @securityDefinitions.apikey X-SIMPLEAUTHLINK-APPID
// @in header
// @name X-SIMPLEAUTHLINK-APPID
// @description Use the received App ID after registering the App (POST /apps).

// @securityDefinitions.apikey X-SIMPLEAUTHLINK-SECRET
// @in header
// @name X-SIMPLEAUTHLINK-SECRET
// @description Use the same secret you provided when creating the App ID. Default: mysupersecret

import (
"context"
"fmt"
Expand All @@ -21,13 +66,13 @@ type Config struct {
Secret string
}

// Service struct represents the API service. It contains the context, cancel
// APIService struct represents the API service. It contains the context, cancel
// function, wait group, configuration, notification queue, API handler and
// HTTP server. The context is used to manage the lifecycle of the service,
// while the wait group is used to wait for background processes to finish.
// The notification queue is used to send notifications, and the API handler
// is used to handle incoming requests.
type Service struct {
type APIService struct {
ctx context.Context
cancel context.CancelFunc
cfg *Config
Expand All @@ -36,18 +81,18 @@ type Service struct {
*http.Server
}

// New function creates a new service instance. It takes a context, a config
// New function creates a new api service instance. It takes a context, a config
// struct, and a notification queue as parameters. It returns a pointer to the
// service instance and an error if something goes wrong during the process.
// The function is responsible for setting up the service and its dependencies.
// It handles the configuration, rate limiting, and HTTP server setup. The
// function is designed to be used as a constructor for the service and is
// responsible for initializing all the necessary components for the service
// to function properly.
func New(ctx context.Context, cfg *Config, nq *notification.Queue) (*Service, error) {
func New(ctx context.Context, cfg *Config, nq *notification.Queue) (*APIService, error) {
internalCtx, cancel := context.WithCancel(ctx)
// create the service
srv := &Service{
srv := &APIService{
ctx: internalCtx,
cancel: cancel,
cfg: cfg,
Expand Down Expand Up @@ -79,7 +124,7 @@ func New(ctx context.Context, cfg *Config, nq *notification.Queue) (*Service, er
}

// Start method starts the service by starting the http server.
func (s *Service) Start() error {
func (s *APIService) Start() error {
// start the api server
if err := s.ListenAndServe(); err != nil && err != http.ErrServerClosed {
return err
Expand All @@ -89,7 +134,7 @@ func (s *Service) Start() error {

// Stop method stops the service. It cancels the context and waits for the
// background processes to finish. It also closes the http server.
func (s *Service) Stop() error {
func (s *APIService) Stop() error {
// cancel the context and wait for the background processes finish
s.cancel()
if err := s.Close(); err != nil {
Expand All @@ -102,7 +147,7 @@ func (s *Service) Stop() error {
// to the health check endpoint and returns true if the response status code
// is 200 OK, otherwise it returns false. If something goes wrong during the
// process, it returns false.
func (s *Service) Ping() bool {
func (s *APIService) Ping() bool {
url := fmt.Sprintf("http://%s:%d%s", s.cfg.Server, s.cfg.ServerPort, HealthCheckPath)
request, err := http.NewRequest(http.MethodGet, url, nil)
if err != nil {
Expand Down
Loading
Loading