From 2cc1147f6dac6cb09a31d2a46acf8183a0e2403a Mon Sep 17 00:00:00 2001 From: Petr Stefan Date: Wed, 1 Feb 2017 11:03:04 +0100 Subject: [PATCH] Mention Swagger UI --- Rewritten-docs.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index bc88e88..616e736 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -3082,15 +3082,6 @@ The REST API is a PHP application run in an HTTP server. Its purpose is providing controlled access to the evaluation backend and storing the state of the application. -@todo: what to mention - - basic - GET, POST, JSON, Header, ... - - endpoint structure, Swager UI - - handling requests, preflight, checking roles with annotation - - Uploading files and file storage - one by one upload endpoint. Explain - different types of the Uploaded files. - - Automatic detection of the runtime environment - users must submit - correctly named files, assuming the RTE from the extensions - ### Used Technologies We chose to use PHP in version 7.0, which was the most recent version at the @@ -3326,6 +3317,20 @@ the `/login` endpoint group. An advantage of this approach is being able control the authentication process completely instead of just receiving session data through a global variable. +### Accessing Endpoints + +The REST API has a [generated documentation](https://recodex.github.io/api/) +describing detailed format of input values as well as response structures +including samples. + +Knowing the exact format of the endpoints allows interacting directly with the +API using any REST client available, for example `curl` or `Postman` Chrome +extension. However, there is a generated [REST +client](https://recodex.github.io/api/ui.html) directly for the ReCodEx API +structure using Swagger UI tool. For each endpoint there is a form with boxes +for all the input parameters including description and data type. The responses +are shown as highlighted JSON. The authorization can be set for whole session at +once using "Authorize" button at the top of the page. ### Permissions @@ -3434,10 +3439,6 @@ validates the file and gives us access to all of the information through an interface of a class and not only using associative arrays. This is very similar to how the job configuration files are processed. -## API Endpoints - -@todo: Tell the user about the generated API reference and how the -Swagger UI can be used to access the API directly. ## Web Application