Basic documentation feature/6-documentation #8
77
README.md
77
README.md
@@ -1,3 +1,76 @@
|
||||
# document-server
|
||||
# @lfk/document-server
|
||||
|
||||
The document generation server responsible for creating pdfs for sponsoring contracts, certificates and more.
|
||||
The document generation server responsible for creating pdfs for sponsoring contracts, certificates and more.
|
||||
This server doesn't interact with any database and can therefor be deployed on it's own.
|
||||
The basic generation mechanism makes the templates and routes interchangeable (if you want to expand or modify it).
|
||||
|
||||
## Quickstart 🐳
|
||||
> Use this to run the document server in docker.
|
||||
|
||||
1. Clone the repo or copy the docker-compose
|
||||
2. Run in the folder that contains the docker-compose file: `docker-compose up -d`
|
||||
3. Visit http://127.0.0.1:4010/docs to check if the server is running
|
||||
|
||||
## Dev Setup 🛠
|
||||
> Local dev setup
|
||||
|
||||
1. Rename the .env.example file to .env (you can adjust app port and other settings, if needed)
|
||||
2. Install Dependencies
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
3. Start the server
|
||||
```bash
|
||||
yarn dev
|
||||
```
|
||||
|
||||
## ENV Vars
|
||||
> You can provide them via .env file or docker env vars.
|
||||
|
||||
| Name | Type | Default | Description
|
||||
| - | - | - | -
|
||||
| APP_PORT | Number | 4010 | The port the backend server listens on. Is optional.
|
||||
| NODE_ENV | String | dev | The apps env - influences debug info.
|
||||
|
||||
## Templates
|
||||
> The document server uses html templates to generate various pdf documents.
|
||||
> The templates are stored in src/templates by default.
|
||||
|
||||
We provide a set of default templates that we use for the ["Lauf für Kaya!" charity run](https://lauf-fuer-kaya.de).
|
||||
We use mustache-style templating strings to fill the templates with real information (exact strings are explained below).
|
||||
You can provide your own templates by replacing the ones we provided before compiling the project or by simply mounting your custom templates into the docker container.
|
||||
|
||||
The server currently needs the following templates to work:
|
||||
* sponsoring_contract.html
|
||||
|
||||
### Sponsoring Contracts
|
||||
|
||||
| Template String | Type | Optional | Description
|
||||
| - | - | - | -
|
||||
| runner_firstname | string | ❌ | The runner's first name
|
||||
| runner_middlename | string | ✅ | The runner's middle name
|
||||
| runner_lastname | string | ❌ | The runner's last name
|
||||
| runner_id | int | ❌ | The runner's id
|
||||
|
||||
## Recommended Editor
|
||||
|
||||
[Visual Studio Code](https://code.visualstudio.com/)
|
||||
|
||||
### Recommended Extensions
|
||||
|
||||
* will be automatically recommended via ./vscode/extensions.json
|
||||
|
||||
## Staging
|
||||
### Branches & Tags
|
||||
* vX.Y.Z: Release tags created from the main branch
|
||||
* The version numbers follow the semver standard
|
||||
* A new release tag automaticly triggers the release ci pipeline
|
||||
* main: Protected "release" branch
|
||||
* The latest tag of the docker image get's build from this
|
||||
* New releases get created as tags from this
|
||||
* dev: Current dev branch for merging the different feature branches and bugfixes
|
||||
* The dev tag of the docker image get's build from this
|
||||
* Only push minor changes to this branch!
|
||||
* To merge a feature branch into this please create a pull request
|
||||
* feature/xyz: Feature branches - nameing scheme: `feature/issueid-title`
|
||||
* bugfix/xyz: Branches for bugfixes - nameing scheme:`bugfix/issueid-title`
|
||||
@@ -1,5 +1,6 @@
|
||||
import { validationMetadatasToSchemas } from "@odit/class-validator-jsonschema";
|
||||
import { Application } from "express";
|
||||
import express, { Application } from "express";
|
||||
import path from 'path';
|
||||
import { getMetadataArgsStorage } from "routing-controllers";
|
||||
import { generateSpec } from '../apispec';
|
||||
|
||||
@@ -18,6 +19,6 @@ export default async (app: Application) => {
|
||||
app.get(["/docs/openapi.json", "/docs/swagger.json"], (req, res) => {
|
||||
res.json(spec);
|
||||
});
|
||||
//app.use('/api/docs', express.static(path.join(__dirname, '../static/docs'), { index: "index.html", extensions: ['html'] }));
|
||||
app.use('/docs', express.static(path.join(__dirname, '../static/docs'), { index: "index.html", extensions: ['html'] }));
|
||||
return app;
|
||||
};
|
||||
|
||||
156
src/static/docs/index.html
Normal file
156
src/static/docs/index.html
Normal file
@@ -0,0 +1,156 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>API Docs</title>
|
||||
<style>
|
||||
:root {
|
||||
--bg-color: #fff;
|
||||
--bg-secondary-color: #f3f3f6;
|
||||
--color-primary: #14854f;
|
||||
--color-lightGrey: #d2d6dd;
|
||||
--color-grey: #747681;
|
||||
--color-darkGrey: #3f4144;
|
||||
--color-error: #d43939;
|
||||
--color-success: #28bd14;
|
||||
--grid-maxWidth: 120rem;
|
||||
--grid-gutter: 2rem;
|
||||
--font-size: 1.6rem;
|
||||
--font-color: #333;
|
||||
--font-family-sans: -apple-system, BlinkMacSystemFont, Avenir, "Avenir Next", "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
|
||||
--font-family-mono: monaco, "Consolas", "Lucida Console", monospace
|
||||
}
|
||||
|
||||
html {
|
||||
-webkit-box-sizing: border-box;
|
||||
box-sizing: border-box;
|
||||
font-size: 62.5%;
|
||||
line-height: 1.15;
|
||||
-ms-text-size-adjust: 100%;
|
||||
-webkit-text-size-adjust: 100%
|
||||
}
|
||||
|
||||
*,
|
||||
:after,
|
||||
:before {
|
||||
-webkit-box-sizing: inherit;
|
||||
box-sizing: inherit
|
||||
}
|
||||
|
||||
body {
|
||||
background-color: var(--bg-color);
|
||||
line-height: 1.6;
|
||||
font-size: var(--font-size);
|
||||
color: var(--font-color);
|
||||
font-family: Segoe UI, Helvetica Neue, sans-serif;
|
||||
font-family: var(--font-family-sans);
|
||||
margin: 0;
|
||||
padding: 0
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-weight: 500;
|
||||
margin: .35em 0 .7em
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-size: 1.5em
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--color-primary);
|
||||
text-decoration: none
|
||||
}
|
||||
|
||||
a:hover:not(.button) {
|
||||
opacity: .75
|
||||
}
|
||||
|
||||
input:not([type=checkbox]):not([type=radio]):not([type=submit]):not([type=color]):not([type=button]):not([type=reset]):not(:disabled):hover {
|
||||
border-color: var(--color-grey)
|
||||
}
|
||||
|
||||
::-webkit-input-placeholder {
|
||||
color: #bdbfc4
|
||||
}
|
||||
|
||||
::-moz-placeholder {
|
||||
color: #bdbfc4
|
||||
}
|
||||
|
||||
:-ms-input-placeholder {
|
||||
color: #bdbfc4
|
||||
}
|
||||
|
||||
::-ms-input-placeholder {
|
||||
color: #bdbfc4
|
||||
}
|
||||
|
||||
.tabs {
|
||||
display: -webkit-box;
|
||||
display: -ms-flexbox;
|
||||
display: flex
|
||||
}
|
||||
|
||||
.tabs a {
|
||||
text-decoration: none
|
||||
}
|
||||
|
||||
.tabs>a {
|
||||
padding: 1rem 2rem;
|
||||
-webkit-box-flex: 0;
|
||||
-ms-flex: 0 1 auto;
|
||||
flex: 0 1 auto;
|
||||
color: var(--color-darkGrey);
|
||||
border-bottom: 2px solid var(--color-lightGrey);
|
||||
text-align: center
|
||||
}
|
||||
|
||||
.tabs>a:hover {
|
||||
opacity: 1;
|
||||
border-bottom: 2px solid var(--color-darkGrey)
|
||||
}
|
||||
|
||||
.is-vertical-align {
|
||||
display: -webkit-box;
|
||||
display: -ms-flexbox;
|
||||
display: flex;
|
||||
-webkit-box-align: center;
|
||||
-ms-flex-align: center;
|
||||
align-items: center
|
||||
}
|
||||
|
||||
.is-center {
|
||||
display: -webkit-box;
|
||||
display: -ms-flexbox;
|
||||
display: flex;
|
||||
-webkit-box-pack: center;
|
||||
-ms-flex-pack: center;
|
||||
justify-content: center
|
||||
}
|
||||
|
||||
.is-center {
|
||||
-webkit-box-align: center;
|
||||
-ms-flex-align: center;
|
||||
align-items: center
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="hero">
|
||||
<div class="logo is-center is-vertical-align">
|
||||
<h3>API Docs</h3>
|
||||
</div>
|
||||
<nav class="tabs is-center">
|
||||
<a href="./redoc">ReDoc</a>
|
||||
<a href="./swaggerui">SwaggerUI</a>
|
||||
<a href="./rapidoc">RapiDoc</a>
|
||||
<a href="./openapi.json">Raw Spec (json)</a>
|
||||
</nav>
|
||||
</div>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
220
src/static/docs/rapidoc-min.js
vendored
Normal file
220
src/static/docs/rapidoc-min.js
vendored
Normal file
File diff suppressed because one or more lines are too long
12
src/static/docs/rapidoc.html
Normal file
12
src/static/docs/rapidoc.html
Normal file
@@ -0,0 +1,12 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<script type="module" src="./rapidoc-min.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<rapi-doc
|
||||
spec-url="/docs/openapi.json"
|
||||
> </rapi-doc>
|
||||
</body>
|
||||
</html>
|
||||
18
src/static/docs/redoc.html
Normal file
18
src/static/docs/redoc.html
Normal file
@@ -0,0 +1,18 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>ReDoc</title>
|
||||
<meta charset="utf-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<redoc spec-url='/docs/openapi.json'></redoc>
|
||||
<script src="./redoc.standalone.js"> </script>
|
||||
</body>
|
||||
</html>
|
||||
103
src/static/docs/redoc.standalone.js
Normal file
103
src/static/docs/redoc.standalone.js
Normal file
File diff suppressed because one or more lines are too long
3
src/static/docs/swagger-ui-bundle.js
Normal file
3
src/static/docs/swagger-ui-bundle.js
Normal file
File diff suppressed because one or more lines are too long
3
src/static/docs/swagger-ui-standalone-preset.js
Normal file
3
src/static/docs/swagger-ui-standalone-preset.js
Normal file
File diff suppressed because one or more lines are too long
8895
src/static/docs/swagger-ui.css
Normal file
8895
src/static/docs/swagger-ui.css
Normal file
File diff suppressed because it is too large
Load Diff
58
src/static/docs/swaggerui.html
Normal file
58
src/static/docs/swaggerui.html
Normal file
@@ -0,0 +1,58 @@
|
||||
<!-- HTML for static distribution bundle build -->
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Swagger UI</title>
|
||||
<link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
|
||||
<style>
|
||||
html
|
||||
{
|
||||
box-sizing: border-box;
|
||||
overflow: -moz-scrollbars-vertical;
|
||||
overflow-y: scroll;
|
||||
}
|
||||
|
||||
*,
|
||||
*:before,
|
||||
*:after
|
||||
{
|
||||
box-sizing: inherit;
|
||||
}
|
||||
|
||||
body
|
||||
{
|
||||
margin:0;
|
||||
background: #fafafa;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div id="swagger-ui"></div>
|
||||
|
||||
<script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
|
||||
<script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
|
||||
<script>
|
||||
window.onload = function() {
|
||||
// Begin Swagger UI call region
|
||||
const ui = SwaggerUIBundle({
|
||||
url: "/docs/openapi.json",
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
SwaggerUIStandalonePreset
|
||||
],
|
||||
plugins: [
|
||||
SwaggerUIBundle.plugins.DownloadUrl
|
||||
],
|
||||
layout: "StandaloneLayout"
|
||||
})
|
||||
// End Swagger UI call region
|
||||
|
||||
window.ui = ui
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user