mirror of
https://github.com/ilri/dspace-statistics-api.git
synced 2025-05-08 14:16:01 +02:00
Add Swagger UI on /swagger
This includes a Swagger UI with an OpenAPI 3.0 JSON schema for easy interactive demonstration and testing of the API. The JSON schema was created with the standalone swagger-editor. Includes tests to make sure that the /swagger and /docs/openapi.json paths are acce- ssible.
This commit is contained in:
@ -1,5 +1,6 @@
|
||||
import falcon
|
||||
import psycopg2.extras
|
||||
from falcon_swagger_ui import register_swaggerui_app
|
||||
|
||||
from .database import DatabaseManager
|
||||
from .stats import get_downloads, get_views
|
||||
@ -14,6 +15,14 @@ class RootResource:
|
||||
resp.body = f.read()
|
||||
|
||||
|
||||
class OpenAPIJSONResource:
|
||||
def on_get(self, req, resp):
|
||||
resp.status = falcon.HTTP_200
|
||||
resp.content_type = "text/html"
|
||||
with open("dspace_statistics_api/docs/openapi.json", "r") as f:
|
||||
resp.body = f.read()
|
||||
|
||||
|
||||
class AllStatisticsResource:
|
||||
@falcon.before(set_statistics_scope)
|
||||
def on_get(self, req, resp):
|
||||
@ -178,4 +187,18 @@ api.add_route("/community/{id_:uuid}", SingleStatisticsResource())
|
||||
api.add_route("/collections", AllStatisticsResource())
|
||||
api.add_route("/collection/{id_:uuid}", SingleStatisticsResource())
|
||||
|
||||
# Swagger configuration
|
||||
SWAGGERUI_URL = "/swagger" # without trailing slash
|
||||
SCHEMA_URL = "/docs/openapi.json"
|
||||
api.add_route("/docs/openapi.json", OpenAPIJSONResource())
|
||||
|
||||
register_swaggerui_app(
|
||||
api,
|
||||
SWAGGERUI_URL,
|
||||
SCHEMA_URL,
|
||||
config={
|
||||
"supportedSubmitMethods": ["get", "post"],
|
||||
},
|
||||
)
|
||||
|
||||
# vim: set sw=4 ts=4 expandtab:
|
||||
|
||||
586
dspace_statistics_api/docs/openapi.json
Normal file
586
dspace_statistics_api/docs/openapi.json
Normal file
@ -0,0 +1,586 @@
|
||||
{
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"version": "1.4.0-dev",
|
||||
"title": "DSpace Statistics API",
|
||||
"description": "A [Falcon-based](https://falcon.readthedocs.io/) web application to make DSpace's item, community, and collection statistics available via a simple REST API. This Swagger interface is powered by [falcon-swagger-ui](https://github.com/rdidyk/falcon-swagger-ui).",
|
||||
"license": {
|
||||
"name": "GPLv3.0",
|
||||
"url": "https://www.gnu.org/licenses/gpl-3.0.en.html"
|
||||
}
|
||||
},
|
||||
"paths": {
|
||||
"/item/{item_uuid}": {
|
||||
"get": {
|
||||
"summary": "Statistics for a specific item",
|
||||
"operationId": "getItem",
|
||||
"tags": [
|
||||
"item"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "item_uuid",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"description": "The UUID of the item to retrieve",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid",
|
||||
"example": "9596aeff-0b90-47d3-9fec-02d578920507"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Item not found"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/items": {
|
||||
"get": {
|
||||
"summary": "Get statistics for all items",
|
||||
"operationId": "getItems",
|
||||
"tags": [
|
||||
"items"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"description": "How many items to return at once (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100,
|
||||
"example": 100
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "page",
|
||||
"in": "query",
|
||||
"description": "Page of results to start on (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0,
|
||||
"example": 0
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A paged array of items",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"summary": "Get statistics for a list of items with an optional date range",
|
||||
"operationId": "postItems",
|
||||
"tags": [
|
||||
"items"
|
||||
],
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100
|
||||
},
|
||||
"page": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0
|
||||
},
|
||||
"dateFrom": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"dateTo": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"items": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
},
|
||||
"example": {
|
||||
"limit": 100,
|
||||
"page": 5,
|
||||
"dateFrom": "2020-01-01T00:00:00Z",
|
||||
"dateTo": "2020-12-31T00:00:00Z",
|
||||
"items": [
|
||||
"f44cf173-2344-4eb2-8f00-ee55df32c76f",
|
||||
"2324aa41-e9de-4a2b-bc36-16241464683e",
|
||||
"8542f9da-9ce1-4614-abf4-f2e3fdb4b305",
|
||||
"0fe573e7-042a-4240-a4d9-753b61233908"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"currentPage": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"totalPages": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"statistics": {
|
||||
"$ref": "#/components/schemas/ListOfElements"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/community/{community_uuid}": {
|
||||
"get": {
|
||||
"summary": "Statistics for a specific community",
|
||||
"operationId": "getCommunity",
|
||||
"tags": [
|
||||
"community"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "community_uuid",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"description": "The UUID of the community to retrieve",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid",
|
||||
"example": "bde7139c-d321-46bb-aef6-ae70799e5edb"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Community not found"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/communities": {
|
||||
"get": {
|
||||
"summary": "Get statistics for all communities",
|
||||
"operationId": "getCommunities",
|
||||
"tags": [
|
||||
"communities"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"description": "How many communities to return at once (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100,
|
||||
"example": 100
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "page",
|
||||
"in": "query",
|
||||
"description": "Zero-based page of results to start on (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0,
|
||||
"example": 0
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A paged array of communities",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"summary": "Get statistics for a list of communities with an optional date range",
|
||||
"operationId": "postCommunities",
|
||||
"tags": [
|
||||
"communities"
|
||||
],
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100
|
||||
},
|
||||
"page": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0
|
||||
},
|
||||
"dateFrom": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"dateTo": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"communities": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
},
|
||||
"example": {
|
||||
"limit": 100,
|
||||
"page": 0,
|
||||
"dateFrom": "2020-01-01T00:00:00Z",
|
||||
"dateTo": "2020-12-31T00:00:00Z",
|
||||
"communities": [
|
||||
"bde7139c-d321-46bb-aef6-ae70799e5edb",
|
||||
"8a8aeed1-077e-4360-bdf8-a5f3020193b1",
|
||||
"47d0498a-203c-407d-afb8-1d44bf29badc",
|
||||
"d3fe99a9-e27d-4035-9339-084c93228c82"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"currentPage": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"totalPages": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"statistics": {
|
||||
"$ref": "#/components/schemas/ListOfElements"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/collection/{collection_uuid}": {
|
||||
"get": {
|
||||
"summary": "Statistics for a specific collection",
|
||||
"operationId": "getCollection",
|
||||
"tags": [
|
||||
"collection"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "collection_uuid",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"description": "The UUID of the collection to retrieve",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid",
|
||||
"example": "49dc95d8-bf2f-4e68-b30f-41ea266c37ae"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Collection not found"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/collections": {
|
||||
"get": {
|
||||
"summary": "Get statistics for all collections",
|
||||
"operationId": "getCollections",
|
||||
"tags": [
|
||||
"collections"
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"description": "How many collections to return at once (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100,
|
||||
"example": 100
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "page",
|
||||
"in": "query",
|
||||
"description": "Zero-based page of results to start on (optional)",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0,
|
||||
"example": 0
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "A paged array of collections",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"summary": "Get statistics for a list of collections with an optional date range",
|
||||
"operationId": "postCollections",
|
||||
"tags": [
|
||||
"collections"
|
||||
],
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 100
|
||||
},
|
||||
"page": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0,
|
||||
"default": 0
|
||||
},
|
||||
"dateFrom": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"dateTo": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
},
|
||||
"collections": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
},
|
||||
"example": {
|
||||
"limit": 100,
|
||||
"page": 2,
|
||||
"dateFrom": "2020-01-01T00:00:00Z",
|
||||
"dateTo": "2020-12-31T00:00:00Z",
|
||||
"collections": [
|
||||
"5eeef6cf-b91b-42d0-9549-ea61bc8a758f",
|
||||
"6aac3269-b4a9-4924-a24d-9e6ee2b410d2",
|
||||
"551698dd-cd2b-4327-948e-54b5eb6deda5",
|
||||
"39358713-bbaf-4149-a453-e2b18c09fd5d"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Expected response to a valid request",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"currentPage": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"totalPages": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"statistics": {
|
||||
"$ref": "#/components/schemas/ListOfElements"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"SingleElementResponse": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"views",
|
||||
"downloads"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
},
|
||||
"views": {
|
||||
"type": "integer",
|
||||
"example": 450
|
||||
},
|
||||
"downloads": {
|
||||
"type": "integer",
|
||||
"example": 1337
|
||||
}
|
||||
}
|
||||
},
|
||||
"ListOfElements": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/SingleElementResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user