Skip to content

Latest commit

 

History

History
182 lines (115 loc) · 4.92 KB

getting-started.md

File metadata and controls

182 lines (115 loc) · 4.92 KB

Getting Started with DOCAT

Using docatl, the docat CLI 🙀

The most convenient way to interact with docat is with it's official CLI tool, docatl.

You can download a standalone binary of the latest release for your platform here or use go or docker to install it.

The commands below contain examples both using curl and docatl. Do note that the host address and api-key can be omitted if specified in a .docatl.yml file. See the docatl documentation for more information.

Use docatl --help to discover all commands available to manage your docat documentation!

API endpoints

The following sections document the RAW API endpoints you can curl.

The API specification is exposed as an OpenAPI Documentation, via Swagger UI at /api/docs and as a pure documentation with redoc at /api/redoc.

Upload your documentation

You can upload any static HTML page by zipping it and uploading the zip file.

Note: if an index.html file is present in the root of the zip file it will be served automatically.

For example to upload the file docs.zip as version 1.0.0 for awesome-project using curl:

curl -X POST -F "[email protected]" http://localhost:8000/api/awesome-project/1.0.0

Using docatl:

docatl push docs.zip awesome-project 1.0.0 --host http://localhost:8000

Any file type can be uploaded. To view an uploaded pdf, specify it's full path:

http://localhost:8000/awesome-project/1.0.0/my_awesome.pdf

You can also manually upload your documentation. A very simple web form can be found under upload.

Tag documentation

After uploading you can tag a specific version. This can be useful when the latest version should be available as http://localhost:8000/docs/awesome-project/latest

To tag the version 1.0.0 as latest for awesome-project:

curl -X PUT http://localhost:8000/api/awesome-project/1.0.0/tags/latest

Using docatl:

docatl tag awesome-project 1.0.0 latest --host http://localhost:8000

Claim Project

Claiming a Project returns a token which can be used for actions which require authentication (for example for deleting a version). Each Project can be claimed exactly once, so best store the token safely.

curl -X GET http://localhost:8000/api/awesome-project/claim

Using docatl:

docatl claim awesome-project --host http://localhost:8000

Authentication

To make an authenticated call, specify a header with the key Docat-Api-Key and your token as the value:

curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0

Using docatl:

docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key <token>

Delete Version

To delete a Project version you need to be authenticated.

To remove the version 1.0.0 from awesome-project:

curl -X DELETE --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/1.0.0

Using docatl:

docatl delete awesome-project 1.0.0 --host http://localhost:8000 --api-key <token>

Upload Project Icon

To upload a icon, you don't need a token, except if you want to replace an existing icon.

To set example-image.png as the icon for awesome-project, which already has an icon:

curl -X POST -F "[email protected]" --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/icon

Using docatl:

docatl push-icon awesome-project example-image.png --host http://localhost:8000 --api-key <token>

Rename a Project

To rename a Project, you need a token.

To rename awesome-project to new-awesome-project:

curl -X PUT --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/rename/new-awesome-project

Using docatl:

docatl rename awesome-project new-awesome-project --host http://localhost:8000 --api-key <token>

Hide a Version

If you want to hide a version from the version select as well as the search results, you can hide it. You need to be authenticated to do this.

To hide version 0.0.1 of awesome-project:

curl -X POST --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/0.0.1/hide

Using docatl:

docatl hide awesome-project 0.0.1 --host http://localhost:8000 --api-key <token>

Show a Version

This is the reverse of hide, and also requires a token.

To show version 0.0.1 of awesome-project again:

curl -X POST --header "Docat-Api-Key: <token>" http://localhost:8000/api/awesome-project/0.0.1/show

Using docatl:

docatl show awesome-project 0.0.1 --host http://localhost:8000 --api-key <token>