Updated documentation

go-shiori · Jul 14, 2023 · a6b70e8 · a6b70e8
1 parent 765683e
commit a6b70e8
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 1 deletion.
diff --git a/docs/API.md b/docs/API.md
@@ -1,5 +1,7 @@
 This is a brief explanation of Shiori's API. For more examples you can import this [collection](https://github.com/go-shiori/shiori/blob/master/docs/postman/shiori.postman_collection.json) in Postman.
 
+> ⚠️ **This is the documentation for the old API. This API is deprecated and will be removed in the future. Please refer and start migrating to the [API v1](./APIv1.md) instead.**
+
 <!-- TOC -->
 
 - [Auth](#auth)

diff --git a/docs/APIv1.md b/docs/APIv1.md
@@ -0,0 +1,18 @@
+# API v1
+
+> ℹ️ **This is the documentation for the new API. This API is still in development and though the finished endpoints should not change please consider that breaking changes may occur once its properly released. If you are looking for the current API, please [see here](./API.md).**
+
+The new API is an ongoing effort to migrate the current API to a more modern and standard API.
+
+The main goals of this new API are:
+- Ease of development
+- Use of a [modern framework](https://gin-gonic.com)
+- Use of a [standard API specification](https://swagger.io/specification/)
+- Self-documented API using [Swag](https://github.com/swaggo/swag)
+- Improved authentication and sessions using [JWT](https://jwt.io)
+- Deduplicate code between the webserver and the API by refactoring the logic into domains
+- Improve testability by using interfaces and dependency injection
+
+The current status of this new API can be checked [here](https://github.com/go-shiori/shiori/issues/640).
+
+Since the API is self-docummented, you can check the API documentation by [running the server locally](./Contribute.md#running-the-server-locally) and visiting the [`/swagger/index.html` endpoint](http://localhost:8080/swagger/index.html).
diff --git a/docs/Contribute.md b/docs/Contribute.md
@@ -1,5 +1,10 @@
 # Contribute
 
+1. [Running the server locally](#running-the-server-locally)
+2. [Updating the API documentation](#updating-the-api-documentation)
+3. [Lint the code](#lint-the-code)
+4. [Running tests](#running-tests)
+
 ## Running the server locally
 
 To run the current development server with the defaults you can run the following command:

diff --git a/docs/index.md b/docs/index.md
@@ -1,8 +1,12 @@
-Shiori is a simple bookmarks manager written in Go language. Intended as a simple clone of [Pocket](https://getpocket.com//). You can use it as command line application or as web application. This application is distributed as a single binary, which means it can be installed and used easily.
+# Documentation
+
+Shiori is a simple bookmarks manager written in Go language. Intended as a simple clone of [Pocket](https://getpocket.com/). You can use it as command line application or as web application. This application is distributed as a single binary, which means it can be installed and used easily.
 
 ## Resources
 
 - [API](./API.md)
+- [APIv1](./APIv1.md) ([What is this?](https://github.com/go-shiori/shiori/issues/640))
+- [Contributing](./Contribute.md)
 - [Configuration](./Configuration.md)
 - [FAQ](./Frequently-Asked-Question.md)
 - [Installation](./Installation.md)