add some brief doc for API

This commit is contained in:
Your Name 2023-06-28 19:48:05 -04:00 committed by Henri Dickson
parent 751eb0f189
commit 771ebbd7ad
4 changed files with 78 additions and 12 deletions

View file

@ -34,7 +34,7 @@
</p>
<details {% if token %}open{% endif %}>
<summary>
<b>Test Access Token</b>
<a>Test Access Token</a>
</summary>
<form method="post" role="group">
{% csrf_token %}
@ -50,6 +50,38 @@
<code>curl -H "Authorization: Bearer YOUR_TOKEN" {{ site_url }}/api/me</code>
</p>
</details>
<br>
<details>
<summary>
<a>How to authorize</a>
</summary>
0. Create an application
<br>
1. Guide your user to open this URL (you must have <code>https://example.org/callback</code> included in the Redirect URIs field)
<input type="text"
value="{{ site_url }}/oauth/authorize/?response_type=code&amp;client_id=CLIENT_ID&amp;redirect_uri=https://example.org/callback"
readonly>
2. Once authorizated by user, it will redirect to <code>https://example.org/callback</code> with a <code>code</code> parameter:
<input type="text"
value="https://example.org/callback?code=AUTH_CODE"
readonly>
3. Obtain access token with the following POST request:
<textarea readonly rows="7">
curl -X POST {{ site_url }}/oauth/token/ \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=CLIENT_ID" \
-d "client_secret=CLIENT_SECRET" \
-d "code=AUTH_CODE" \
-d "redirect_uri=https://example.org/callback" \
-d "grant_type=authorization_code"</textarea>
and access token will be returned in the response:
<textarea readonly rows="1">{"access_token": "ACCESS_TOKEN", "expires_in": 31536000, "token_type": "Bearer", "scope": "read write", "refresh_token": "REFRESH_TOKEN"}</textarea>
4. Use the access token to access protected endpoints like <code>/api/me</code>
<textarea readonly rows="1">curl -H "Authorization: Bearer ACCESS_TOKEN" -X GET http://localhost:8000/api/me</textarea>
and response will be returned accordingly:
<textarea readonly rows="1">{"url": "https://neodb.social/users/xxx@yyy.zzz/", "external_acct": "xxx@yyy.zzz", "display_name": "XYZ", "avatar": "https://yyy.zzz/xxx.gif"}</textarea>
more endpoints can be found in API Documentation below.
</details>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.18.3/swagger-ui-bundle.min.js"
integrity="sha512-PijkKcRp7VDW1K2S8nNgljcNRrEQmazUc8sPiVRMciEuNzJzz2KeKb2Cjz/HdjZrKwmEYEyhOFZlOi0xzqWdqg=="

View file

@ -13,15 +13,6 @@
value="{{ application.client_id }}"
readonly>
</li>
<li>
<p>
<b>{% trans "Client Secret" %}</b>
</p>
<input class="input-block-level"
type="text"
value="{{ application.client_secret }}"
readonly>
</li>
<li>
<p>
<b>{% trans "URL" %}</b>
@ -37,10 +28,12 @@
<li>
<p>
<b>{% trans "Redirect Uris" %}</b>
{% if not application.redirect_uris %}WARNING: no redirect uris have been set, authorization may not work.{% endif %}
</p>
<textarea class="input-block-level" readonly>{{ application.redirect_uris }}</textarea>
<textarea readonly>{{ application.redirect_uris }}</textarea>
</li>
</ul>
<hr>
<div class="btn-toolbar">
<a class="btn" href="{% url "oauth2_provider:list" %}">{% trans "Go Back" %}</a>
<a class="btn btn-primary"

View file

@ -0,0 +1,39 @@
{% extends "oauth2_provider/base.html" %}
{% load i18n %}
{% block content %}
<form method="post"
action="{% block app-form-action-url %}{% url 'oauth2_provider:update' application.id %}{% endblock app-form-action-url %}">
<h3>
{% block app-form-title %}
{% trans "Edit application" %} {{ application.name }}
{% endblock app-form-title %}
</h3>
{% csrf_token %}
<fieldset>
{% for field in form %}
<label {% if field.errors %}aria-invalid="true"{% endif %}>
{{ field.label }}
{% if field.name == 'client_secret' %}
<small><b>(please save it properly as it will NOT be editable or shown again)</b></small>
{% elif field.name == 'description' %}
<small>(markdown syntax supported)</small>
{% endif %}
{{ field }}
{% for error in field.errors %}<small>{{ error }}</small>{% endfor %}
</label>
{% endfor %}
</fieldset>
<div class="control-group {% if form.non_field_errors %}error{% endif %}">
{% for error in form.non_field_errors %}<span class="help-inline">{{ error }}</span>{% endfor %}
</div>
<div class="control-group">
<div class="controls">
<a class="btn"
href="{% block app-form-back-url %}{% url "oauth2_provider:detail" application.id %}{% endblock app-form-back-url %}">
{% trans "Go Back" %}
</a>
<button type="submit" class="btn btn-primary">{% trans "Save" %}</button>
</div>
</div>
</form>
{% endblock %}

View file

@ -29,6 +29,7 @@ class ApplicationRegistration(BaseApplicationRegistration):
"name",
"url",
"description",
"client_secret",
"redirect_uris",
# "post_logout_redirect_uris",
),
@ -38,7 +39,7 @@ class ApplicationRegistration(BaseApplicationRegistration):
form.instance.user = self.request.user
if not form.instance.id:
form.instance.client_id = generate_client_id()
form.instance.client_secret = generate_client_secret()
# form.instance.client_secret = generate_client_secret()
form.instance.client_type = Application.CLIENT_CONFIDENTIAL
form.instance.authorization_grant_type = (
Application.GRANT_AUTHORIZATION_CODE
@ -54,6 +55,7 @@ class ApplicationUpdate(BaseApplicationUpdate):
"name",
"url",
"description",
# "client_secret",
"redirect_uris",
# "post_logout_redirect_uris",
),