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
6 changes: 1 addition & 5 deletions .github/workflows/reuse-quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,11 @@ jobs:

- uses: actions/setup-node@v7
with:
node-version: 24
node-version-file: .nvmrc
cache: 'npm'

- name: Install dependencies
run: npm ci

- name: Run quality checks
run: npm run quality

- name: Docker logs in case of failure
if: failure()
run: docker compose logs data-fair
22 changes: 18 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,9 +1,23 @@
# dependencies and generated code
node_modules/
api/config/local-*
.type/

# tests de snapshot visuels : locaux uniquement, jamais commités
tests/**/*.snap.spec.ts
tests/**/*-snapshots/
# local environment and data
.env
**/config/local-*
data/
dev/logs/

# test output
test-results/
playwright-report/

# agent working files
docs/superpowers/
.superpowers/
.playwright-mcp/

# openapi-viewer
# visual snapshot tests: local only, never committed
tests/**/*.snap.spec.ts
tests/**/*-snapshots/
32 changes: 12 additions & 20 deletions .zellij.kdl
Original file line number Diff line number Diff line change
@@ -1,28 +1,20 @@
// Dev environment of openapi-viewer, see @data-fair/lib-dev. Agents: npx --no df-dev status | logs <pane> | restart <pane>
layout {
pane {
split_direction "vertical"
pane name="openapi-viewer" borderless=true {
command "${DEV_SHELL}"
args "-ic" "nvm use > /dev/null 2>&1 && bash"
}
pane name="deps" {
command "${DEV_SHELL}"
args "-ic" "nvm use > /dev/null 2>&1 && npm run dev-deps && watch -n 4 \"docker compose ps --all --format 'table {{.Name}}\t{{.Status}}'\""
pane split_direction="vertical" {
pane name="openapi-viewer" borderless=true
pane name="status" command="./node_modules/.bin/df-status" {
args "--start-deps"
}
}
pane {
split_direction "vertical"
pane name="ui" {
command "${DEV_SHELL}"
args "-ic" "nvm use > /dev/null 2>&1 && npm -w ui run dev"
pane split_direction="vertical" {
pane name="ui" command="bash" {
args "-c" "cd ui && FORCE_COLOR=1 NODE_CONFIG_DIR=../api/config/ exec ../node_modules/.bin/df-mem-cap vite --port $DEV_UI_PORT"
}
pane name="api" {
command "${DEV_SHELL}"
args "-ic" "nvm use > /dev/null 2>&1 && npm -w api run dev"
pane name="api" command="bash" {
args "-c" "./node_modules/.bin/df-dev wait-deps && cd api && FORCE_COLOR=1 NODE_ENV=development exec ../node_modules/.bin/nodemon -e js,mjs,ts,json index.ts"
}
}
pane size=1 borderless=true {
command "bash"
args "-ic" "echo -n -e \"Dev server available at \\e[1;96mhttp://localhost:5600\\033[0m\""
pane name="url" size=1 borderless=true command="bash" {
args "-c" "echo -n -e \"Dev server available at \\e[1;96mhttp://$DEV_HOST:$NGINX_PORT/openapi-viewer/dev\\e[0m\"; exec sleep infinity"
}
}
77 changes: 21 additions & 56 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,88 +4,53 @@

- A Javascript/Typescript IDE with [Vue.js](https://vuejs.org/) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) support.
- A recent [Docker](https://docs.docker.com/engine/install/) installation.
- [Node.js v22+](https://nodejs.org/)
- [Node.js v24.22.1+](https://nodejs.org/)
- [zellij](https://zellij.dev/) >= 0.44.

## Install dependencies

1) Install npm dependencies for all workspaces :
Install npm dependencies for all workspaces, then generate `.env` (ports), the types and the UI build:

```sh
npm i
npm ci
npx --no df-dev setup
```

2) Pull images at first and then once in a while :
Pull images at first and then once in a while:

```sh
docker compose pull
docker compose --profile '*' pull
```

3) Then run the containers :
## Run the development servers

```sh
npm run dev-deps
```

*Stop the containers with this command :*

```sh
npm run stop-dev-deps
```

4) Generates the types based on schemas :
The UI is a [Vite](https://vite.dev/) + Vue project, the API a small [Express](https://expressjs.com) server.
The development servers run in a zellij session, see `@data-fair/lib-dev`:

```sh
npm run build-types
```

## Building and running the Docker images

```sh
docker build --progress=plain --target=main -t data-fair/openapi-viewer:dev .
npm run dev-zellij
```

## All-in-one development
The session prints the URL of the dev page, which links to the example documentations. The dev environment
runs simple-directory (theme, language, admin session), like the viewer embedded in the data-fair stack; the
standalone mode (`USE_SIMPLE_DIRECTORY=false`, see the README) needs none of it.

You can run all services at once thanks to Zellij.
Agents operate the running environment with `npx --no df-dev status | logs <pane> | restart <pane>`.

<details>
<summary>First time instructions</summary>
## Working on types

1) Install Rust's Cargo
Update the types based on schemas:

```sh
curl https://sh.rustup.rs -sSf | sh
# choose 1 when prompted
```

2) Install Zellij

```sh
cargo install --locked zellij
```

3) Install NVM

```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install
npm run build-types
```

</details>

Run the Zellij command :
## Building the Docker image

```sh
npm run dev-zellij
docker build --progress=plain --target=main -t data-fair/openapi-viewer:dev .
```

Access the running services at <http://localhost:5600/openapi-viewer>

*Tips :*

- Use <kbd>Ctrl</kbd> + <kbd>Q</kbd> to quit Zellij.
- Click on a panel, then use <kbd>Ctrl</kbd> + <kbd>C</kbd> then <kbd>Esc</kbd> to stop a terminal and regain access of the panel.

## Tests

Tests use [Playwright](https://playwright.dev/). Three projects are defined in
Expand All @@ -102,7 +67,7 @@ Tests use [Playwright](https://playwright.dev/). Three projects are defined in
# unit tests only (no stack needed)
npm run test-unit

# e2e / snapshot need the stack running (dev-deps + api + ui, see above)
# e2e / snapshot need the dev environment running (see above)
npm run test-e2e
npm run test-snapshot

Expand Down
19 changes: 13 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,20 @@
# OpenAPI viewer
# <img alt="Data FAIR logo" src="https://cdn.jsdelivr.net/gh/data-fair/data-fair@master/ui/src/assets/logo.svg" width="40"> @data-fair/openapi-viewer

This service is designed to easily browse and test a REST API described with the [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification).
![GitHub License](https://img.shields.io/github/license/data-fair/openapi-viewer) ![GitHub package.json version](https://img.shields.io/github/package-json/v/data-fair/openapi-viewer)
*Browse and test a REST API described with the [OpenAPI 3 Specification](https://github.com/OAI/OpenAPI-Specification).*

Part of the [Data Fair](https://datafair.cloud) ecosystem, also usable on its own.

## Sponsors

| | Click [here to support the development of this project](https://github.com/sponsors/koumoul-dev). |
|-|-|
| ![Koumoul logo](https://koumoul.com/static/logo-slogan.png) | [Koumoul](https://koumoul.com) develops the Data Fair ecosystem and hosts it as an online service. |
| ![Dawizz logo](https://dawizz.fr/logo-Dawizz-all-about-your-data-home.png) | [Dawizz](https://dawizz.fr) uses the Data Fair ecosystem inside its platform and supports its development. |
<a href="https://koumoul.com"><img alt="Koumoul logo" src="https://cdn.jsdelivr.net/gh/data-fair/data-fair@master/docs/assets/koumoul-logo.png" height="56" align="left"></a>

**[Koumoul](https://koumoul.com)** · *La donnée accessible*<br>
Koumoul develops the Data Fair ecosystem and hosts it as an online service.

<br clear="left">

Click [here to support the development of this project](https://github.com/sponsors/koumoul-dev).

## Parameters

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
module.exports = {
export default {
defaultUrl: 'DEFAULT_URL',
allowedUrls: {
__name: 'ALLOWED_URLS',
Expand Down
2 changes: 1 addition & 1 deletion api/config/default.cjs → api/config/default.mjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
module.exports = {
export default {
defaultUrl: undefined,
allowedUrls: {},
port: 8080,
Expand Down
11 changes: 0 additions & 11 deletions api/config/development.cjs

This file was deleted.

17 changes: 17 additions & 0 deletions api/config/development.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import dotenv from 'dotenv'
dotenv.config({ path: ['.env', '../.env'], quiet: true })

if (!process.env.DEV_API_PORT) throw new Error('missing DEV_API_PORT env variable, run "npx --no df-dev setup"')

export default {
defaultUrl: 'examples/fulltest.json',
allowedUrls: {
// fetched by the browser, through nginx
example: `http://${process.env.DEV_HOST}:${process.env.NGINX_PORT}/openapi-viewer/examples/{filename}`,
petstore: 'https://petstore.swagger.io/v2/swagger.json'
},
port: Number(process.env.DEV_API_PORT),
serveUi: false,
useSimpleDirectory: true,
privateDirectoryUrl: `http://localhost:${process.env.SD_PORT}`,
}
2 changes: 0 additions & 2 deletions api/config/production.cjs

This file was deleted.

2 changes: 2 additions & 0 deletions api/config/production.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
export default {
}
4 changes: 0 additions & 4 deletions api/config/test.cjs

This file was deleted.

7 changes: 7 additions & 0 deletions api/nodemon.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"ignoreRoot": [],
"ignore": ["node_modules/"],
"execMap": {
"ts": "node"
}
}
8 changes: 3 additions & 5 deletions api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,13 @@
"name": "api",
"main": "index.ts",
"type": "module",
"scripts": {
"dev": "NODE_ENV=development node --watch --experimental-strip-types index.ts"
},
"scripts": {},
"imports": {
"#config": "./src/config.ts"
},
"dependencies": {
"@data-fair/lib-express": "^1.27.0",
"@data-fair/lib-node": "^2.12.1",
"@data-fair/lib-express": "^2.0.0",
"@data-fair/lib-node": "^3.0.0",
"config": "^5.0.1",
"express": "^5.0.1",
"http-terminator": "^3.2.0",
Expand Down
5 changes: 5 additions & 0 deletions api/src/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.use('/api/admin', adminRouter)

// no dependency to check: answering is enough (dev readiness, container healthcheck)
app.get('/api/ping', (req, res) => {
res.send('ok')
})

if (config.serveUi) {
app.use(await createSpaMiddleware(resolve(import.meta.dirname, '../../ui/dist'), uiConfig, {
extraHtmlTemplateParams: { SITE_RESOURCES: siteResourcesHtml },
Expand Down
3 changes: 1 addition & 2 deletions api/src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@ import type { ApiConfig } from '../config/type/index.ts'
import { assertValid } from '../config/type/index.ts'
import config from 'config'

// we reload the config instead of using the singleton from the config module for testing purposes
const apiConfig = process.env.NODE_ENV === 'test' ? config.util.loadFileConfigs(process.env.NODE_CONFIG_DIR, { skipConfigSources: true }) : config
const apiConfig = config
assertValid(apiConfig, { lang: 'en', name: 'config', internal: true })

export default apiConfig as ApiConfig
Expand Down
19 changes: 19 additions & 0 deletions dev/dev.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"ports": [
"NGINX_PORT",
"DEV_API_PORT",
"DEV_UI_PORT",
"DEV_UI_HMR_PORT",
"MONGO_PORT",
"SD_PORT"
],
"panes": {
"api": {
"ready": "http://localhost:${DEV_API_PORT}/api/ping"
},
"ui": {
"ready": "http://localhost:${DEV_UI_PORT}/openapi-viewer/"
}
},
"url": "http://${DEV_HOST}:${NGINX_PORT}/openapi-viewer/dev"
}
Loading
Loading