Commit 99ff8169 authored by Eliot Berriot's avatar Eliot Berriot
Browse files

Merge branch '178-api-documentation' into 'develop'

Resolve "Document important API features"

Closes #178

See merge request funkwhale/funkwhale!166
parents aba595ac 56d9c587
......@@ -89,3 +89,4 @@ data/
.env
po/*.po
docs/swagger
......@@ -92,12 +92,14 @@ build_front:
pages:
stage: test
image: python:3.6-alpine
image: python:3.6
variables:
BUILD_PATH: "../public"
before_script:
- cd docs
script:
- pip install sphinx
- python -m sphinx . ../public
- ./build_docs.sh
artifacts:
paths:
- public
......
......@@ -377,6 +377,7 @@ REST_FRAMEWORK = {
),
'DEFAULT_AUTHENTICATION_CLASSES': (
'funkwhale_api.common.authentication.JSONWebTokenAuthenticationQS',
'funkwhale_api.common.authentication.BearerTokenHeaderAuth',
'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
'rest_framework.authentication.SessionAuthentication',
'rest_framework.authentication.BasicAuthentication',
......
......@@ -29,9 +29,6 @@ class TokenHeaderAuth(BaseJSONWebTokenAuthentication):
class TokenAuthMiddleware:
"""
Custom middleware (insecure) that takes user IDs from the query string.
"""
def __init__(self, inner):
# Store the ASGI application we were passed
......
from django.utils.encoding import smart_text
from django.utils.translation import ugettext as _
from rest_framework import exceptions
from rest_framework_jwt import authentication
from rest_framework_jwt.settings import api_settings
......@@ -18,3 +21,37 @@ class JSONWebTokenAuthenticationQS(
def authenticate_header(self, request):
return '{0} realm="{1}"'.format(
api_settings.JWT_AUTH_HEADER_PREFIX, self.www_authenticate_realm)
class BearerTokenHeaderAuth(
authentication.BaseJSONWebTokenAuthentication):
"""
For backward compatibility purpose, we used Authorization: JWT <token>
but Authorization: Bearer <token> is probably better.
"""
www_authenticate_realm = 'api'
def get_jwt_value(self, request):
auth = authentication.get_authorization_header(request).split()
auth_header_prefix = 'bearer'
if not auth:
if api_settings.JWT_AUTH_COOKIE:
return request.COOKIES.get(api_settings.JWT_AUTH_COOKIE)
return None
if smart_text(auth[0].lower()) != auth_header_prefix:
return None
if len(auth) == 1:
msg = _('Invalid Authorization header. No credentials provided.')
raise exceptions.AuthenticationFailed(msg)
elif len(auth) > 2:
msg = _('Invalid Authorization header. Credentials string '
'should not contain spaces.')
raise exceptions.AuthenticationFailed(msg)
return auth[1]
def authenticate_header(self, request):
return '{0} realm="{1}"'.format('Bearer', self.www_authenticate_realm)
......@@ -20,6 +20,9 @@ class ListenableMixin(filters.FilterSet):
class ArtistFilter(ListenableMixin):
q = fields.SearchFilter(search_fields=[
'name',
])
class Meta:
model = models.Artist
......
Foundations for API documentation with Swagger (#178)
......@@ -123,6 +123,15 @@ services:
- '35730:35730'
- '8001:8001'
api-docs:
image: swaggerapi/swagger-ui
environment:
- "API_URL=/swagger.yml"
ports:
- '8002:8080'
volumes:
- "./api/docs/swagger.yml:/usr/share/nginx/html/swagger.yml"
networks:
internal:
federation:
......
Funkwhale API
=============
Funkwhale API is still a work in progress and should not be considered as
stable. We offer an `interactive documentation using swagger </swagger/>`_
were you can browse available endpoints and try the API.
#!/bin/bash -eux
# Building sphinx and swagger docs
python -m sphinx . $BUILD_PATH
TARGET_PATH="$BUILD_PATH/swagger" ./build_swagger.sh
#!/bin/bash -eux
SWAGGER_VERSION="3.13.6"
TARGET_PATH=${TARGET_PATH-"swagger"}
rm -rf $TARGET_PATH /tmp/swagger-ui
git clone --branch="v$SWAGGER_VERSION" --depth=1 "https://github.com/swagger-api/swagger-ui.git" /tmp/swagger-ui
mv /tmp/swagger-ui/dist $TARGET_PATH
cp swagger.yml $TARGET_PATH
sed -i "s,http://petstore.swagger.io/v2/swagger.json,swagger.yml,g" $TARGET_PATH/index.html
......@@ -16,6 +16,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
configuration
importing-music
federation
api
upgrading
third-party
changelog
......
openapi: "3.0"
info:
description: "Documentation for [Funkwhale](https://funkwhale.audio) API. The API is **not** stable yet."
version: "1.0.0"
title: "Funkwhale API"
servers:
- url: https://demo.funkwhale.audio/api/v1
description: Demo server
- url: https://node1.funkwhale.test/api/v1
description: Node 1 (local)
components:
securitySchemes:
jwt:
type: http
scheme: bearer
bearerFormat: JWT
description: "You can get a token by using the /token endpoint"
security:
- jwt: []
paths:
/token/:
post:
tags:
- "auth"
description:
Obtain a JWT token you can use for authenticating your next requests.
security: []
responses:
'200':
description: Successfull auth
'400':
description: Invalid credentials
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
username:
type: "string"
example: "demo"
password:
type: "string"
example: "demo"
/artists/:
get:
tags:
- "artists"
parameters:
- name: "q"
in: "query"
description: "Search query used to filter artists"
schema:
required: false
type: "string"
example: "carpenter"
- name: "listenable"
in: "query"
description: "Filter/exclude artists with listenable tracks"
schema:
required: false
type: "boolean"
responses:
200:
content:
application/json:
schema:
type: "object"
properties:
count:
$ref: "#/properties/resultsCount"
results:
type: "array"
items:
$ref: "#/definitions/ArtistNested"
properties:
resultsCount:
type: "integer"
format: "int64"
description: "The total number of resources matching the request"
mbid:
type: "string"
formats: "uuid"
description: "A musicbrainz ID"
definitions:
Artist:
type: "object"
properties:
mbid:
required: false
$ref: "#/properties/mbid"
id:
type: "integer"
format: "int64"
example: 42
name:
type: "string"
example: "System of a Down"
creation_date:
type: "string"
format: "date-time"
ArtistNested:
type: "object"
allOf:
- $ref: "#/definitions/Artist"
- type: "object"
properties:
albums:
type: "array"
items:
$ref: "#/definitions/AlbumNested"
Album:
type: "object"
properties:
mbid:
required: false
$ref: "#/properties/mbid"
id:
type: "integer"
format: "int64"
example: 16
artist:
type: "integer"
format: "int64"
example: 42
title:
type: "string"
example: "Toxicity"
creation_date:
type: "string"
format: "date-time"
release_date:
type: "string"
required: false
format: "date"
example: "2001-01-01"
AlbumNested:
type: "object"
allOf:
- $ref: "#/definitions/Album"
- type: "object"
properties:
tracks:
type: "array"
items:
$ref: "#/definitions/Track"
Track:
type: "object"
properties:
mbid:
required: false
$ref: "#/properties/mbid"
id:
type: "integer"
format: "int64"
example: 66
artist:
type: "integer"
format: "int64"
example: 42
album:
type: "integer"
format: "int64"
example: 16
title:
type: "string"
example: "Chop Suey!"
position:
required: false
description: "Position of the track in the album"
type: "number"
minimum: 1
example: 1
creation_date:
type: "string"
format: "date-time"
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment