Add OpenAPI documentation (#48)
This commit is contained in:
Vic Demuzere
GitHub
parent
14b5801f37
commit
c8b9887af6
5 changed files with 156 additions and 3 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -2,6 +2,7 @@ frontend/app.js
|
|||
frontend/app.js.LICENSE.txt
|
||||
frontend/css
|
||||
frontend/js
|
||||
frontend/api.html
|
||||
frontend/locale/*.untranslated.json
|
||||
frontend/webfonts
|
||||
frontend/*.woff2
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ RUN set -ex \
|
|||
tar \
|
||||
unzip \
|
||||
&& make -C src -f ../Makefile generate-inner \
|
||||
&& make download_libs \
|
||||
&& make download_libs generate-apidocs \
|
||||
&& go install \
|
||||
-ldflags "-X main.version=$(git describe --tags --always || echo dev)" \
|
||||
-mod=readonly
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ RUN set -ex \
|
|||
tar \
|
||||
unzip \
|
||||
&& make -C src -f ../Makefile generate-inner \
|
||||
&& make download_libs \
|
||||
&& make download_libs generate-apidocs \
|
||||
&& go install \
|
||||
-ldflags "-X main.version=$(git describe --tags --always || echo dev)" \
|
||||
-mod=readonly
|
||||
|
|
|
|||
7
Makefile
7
Makefile
|
|
@ -6,12 +6,17 @@ default: generate download_libs
|
|||
generate:
|
||||
docker run --rm -i -v $(CURDIR):$(CURDIR) -w $(CURDIR) node:14-alpine \
|
||||
sh -exc "apk add make && make -C src -f ../Makefile generate-inner && chown -R $(shell id -u) frontend src/node_modules"
|
||||
docker run --rm -ti -v $(CURDIR):$(CURDIR) -w $(CURDIR) node:14-alpine \
|
||||
sh -exc "apk add make && make generate-apidocs && chown -R $(shell id -u) frontend"
|
||||
|
||||
generate-apidocs:
|
||||
npx redoc-cli bundle docs/openapi.yaml --disableGoogleFont true -o frontend/api.html
|
||||
|
||||
generate-inner:
|
||||
npx npm@lts ci
|
||||
npx npm@lts run build
|
||||
|
||||
publish: download_libs
|
||||
publish: download_libs generate-apidocs
|
||||
$(MAKE) -C src -f ../Makefile generate-inner
|
||||
curl -sSLo golang.sh https://raw.githubusercontent.com/Luzifer/github-publish/master/golang.sh
|
||||
bash golang.sh
|
||||
|
|
|
|||
147
docs/openapi.yaml
Normal file
147
docs/openapi.yaml
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
description: >
|
||||
OTS is a one-time-secret sharing platform.
|
||||
|
||||
|
||||
When using the web application, the secret is encrypted with a symmetric
|
||||
256bit AES encryption in the browser before being sent to the server.
|
||||
Afterwards an URL containing the ID of the secret and the password is
|
||||
generated. The password is never sent to the server so the server will never
|
||||
be able to decrypt the secrets it delivers with a reasonable effort.
|
||||
|
||||
|
||||
This API allows you to store and read the same secrets as the web
|
||||
application.
|
||||
title: Luzifer/OTS API
|
||||
version: 0.x
|
||||
externalDocs:
|
||||
description: Luzifer/OTS on Github
|
||||
url: https://github.com/Luzifer/ots
|
||||
servers:
|
||||
- url: https://ots.fyi/api
|
||||
description: Public hosted instance
|
||||
paths:
|
||||
/create:
|
||||
post:
|
||||
summary: Store a new secret on the OTS server
|
||||
description: >-
|
||||
You should encrypt the secret prior to sending it to the server. For
|
||||
maximum compatibility, [use the same encryption as the web
|
||||
application](https://github.com/Luzifer/ots). Plain text secrets are
|
||||
supported but not recommended.
|
||||
|
||||
|
||||
To generate a URL that works with the web application, append
|
||||
`#SECRET_ID|PASSWORD` after the URL. For an instance on
|
||||
`https://ots.fyi`, the example response in this documentation would
|
||||
become `https://ots.fyi/#5e0065ee-5734-4548-9fd3-bb0bcd4c899d|mypass`.
|
||||
Note that you should correctly [percent
|
||||
encode](https://datatracker.ietf.org/doc/html/rfc3986) the `|` (pipe)
|
||||
character for it to work in all browsers.
|
||||
operationId: createSecret
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
multipart/form-data:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Secret'
|
||||
responses:
|
||||
'200':
|
||||
description: Reference to the newly stored secret.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreatedSecret'
|
||||
'400':
|
||||
description: Secret missing or invalid JSON body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'500':
|
||||
description: Internal error, nothing is wrong with the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/get/{id}:
|
||||
get:
|
||||
summary: Retrieve an existing secret from the OTS server
|
||||
description: >-
|
||||
You may need to decrypt the secret after retrieving it. For maximum
|
||||
compatibility, [use the same encryption as the web
|
||||
application](https://github.com/Luzifer/ots). Plain text secrets are
|
||||
supported but not recommended.
|
||||
operationId: getSecret
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
schema:
|
||||
type: string
|
||||
example: 5e0065ee-5734-4548-9fd3-bb0bcd4c899d
|
||||
required: true
|
||||
description: Reference to the stored secret.
|
||||
responses:
|
||||
'200':
|
||||
description: Stored secret contents.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RetrievedSecret'
|
||||
'400':
|
||||
description: Secret ID missing or invalid.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'404':
|
||||
description: Secret does not exist, may be read by someone else.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'500':
|
||||
description: Internal error, nothing is wrong with the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
schemas:
|
||||
Secret:
|
||||
type: object
|
||||
properties:
|
||||
secret:
|
||||
type: string
|
||||
example: U2FsdGVkX18wJtHr6YpTe8QrvMUUdaLZ+JMBNi1OvOQ=
|
||||
required:
|
||||
- secret
|
||||
CreatedSecret:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
secret_id:
|
||||
type: string
|
||||
example: 5e0065ee-5734-4548-9fd3-bb0bcd4c899d
|
||||
RetrievedSecret:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
secret:
|
||||
type: string
|
||||
example: U2FsdGVkX18wJtHr6YpTe8QrvMUUdaLZ+JMBNi1OvOQ=
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
error:
|
||||
type: string
|
||||
example: Something went wrong.
|
||||
Loading…
Reference in a new issue