Add OpenAPI documentation (#48)

This commit is contained in:
Vic Demuzere 2021-09-27 00:52:44 +02:00 committed by GitHub
parent 14b5801f37
commit c8b9887af6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 156 additions and 3 deletions

1
.gitignore vendored
View File

@ -2,6 +2,7 @@ frontend/app.js
frontend/app.js.LICENSE.txt frontend/app.js.LICENSE.txt
frontend/css frontend/css
frontend/js frontend/js
frontend/api.html
frontend/locale/*.untranslated.json frontend/locale/*.untranslated.json
frontend/webfonts frontend/webfonts
frontend/*.woff2 frontend/*.woff2

View File

@ -17,7 +17,7 @@ RUN set -ex \
tar \ tar \
unzip \ unzip \
&& make -C src -f ../Makefile generate-inner \ && make -C src -f ../Makefile generate-inner \
&& make download_libs \ && make download_libs generate-apidocs \
&& go install \ && go install \
-ldflags "-X main.version=$(git describe --tags --always || echo dev)" \ -ldflags "-X main.version=$(git describe --tags --always || echo dev)" \
-mod=readonly -mod=readonly

View File

@ -17,7 +17,7 @@ RUN set -ex \
tar \ tar \
unzip \ unzip \
&& make -C src -f ../Makefile generate-inner \ && make -C src -f ../Makefile generate-inner \
&& make download_libs \ && make download_libs generate-apidocs \
&& go install \ && go install \
-ldflags "-X main.version=$(git describe --tags --always || echo dev)" \ -ldflags "-X main.version=$(git describe --tags --always || echo dev)" \
-mod=readonly -mod=readonly

View File

@ -6,12 +6,17 @@ default: generate download_libs
generate: generate:
docker run --rm -i -v $(CURDIR):$(CURDIR) -w $(CURDIR) node:14-alpine \ 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" 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: generate-inner:
npx npm@lts ci npx npm@lts ci
npx npm@lts run build npx npm@lts run build
publish: download_libs publish: download_libs generate-apidocs
$(MAKE) -C src -f ../Makefile generate-inner $(MAKE) -C src -f ../Makefile generate-inner
curl -sSLo golang.sh https://raw.githubusercontent.com/Luzifer/github-publish/master/golang.sh curl -sSLo golang.sh https://raw.githubusercontent.com/Luzifer/github-publish/master/golang.sh
bash golang.sh bash golang.sh

147
docs/openapi.yaml Normal file
View 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.