rixty
/
AzuraCast
mirror of https://github.com/AzuraCast/AzuraCast.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

API documentation cleanup. [skip ci]

This commit is contained in:
Buster Silver 2017-06-17 14:39:21 -05:00
parent 6c84a8bb2f
commit 4f682475be
8 changed files with 61 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
app/models/Api/NowPlayingListeners.php
View File

@ -21,21 +21,21 @@ class NowPlayingListeners
/**
* Current listeners, either unique (if supplied) or total (non-unique)
* @SWG\Property(example="15")
* @SWG\Property(example=15)
* @var int
*/
public $current;
/**
* Total unique current listeners
* @SWG\Property(example="15")
* @SWG\Property(example=15)
* @var int
*/
public $unique;
/**
* Total non-unique current listeners
* @SWG\Property(example="20")
* @SWG\Property(example=20)
* @var int
*/
public $total;

10
app/models/Api/StationMount.php
View File

@ -12,7 +12,7 @@ class StationMount
/**
* Mount point name/URL
*
* @SWG\Property
* @SWG\Property(example="/radio.mp3")
* @var string
*/
public $name;
@ -20,7 +20,7 @@ class StationMount
/**
* If the mount is the default mount for the parent station
*
* @SWG\Property
* @SWG\Property(example=true)
* @var bool
*/
public $is_default;
@ -28,7 +28,7 @@ class StationMount
/**
* Full listening URL specific to this mount
*
* @SWG\Property
* @SWG\Property(example="http://localhost:8000/radio.mp3")
* @var string
*/
public $url;
@ -36,7 +36,7 @@ class StationMount
/**
* Bitrate (kbps) of the broadcasted audio (if known)
*
* @SWG\Property
* @SWG\Property(example=128)
* @var int
*/
public $bitrate;
@ -44,7 +44,7 @@ class StationMount
/**
* Audio encoding format of broadcasted audio (if known)
*
* @SWG\Property
* @SWG\Property(example="mp3")
* @var string
*/
public $format;

2
app/modules/api/controllers/ListenersController.php
View File

@ -8,7 +8,7 @@ class ListenersController extends BaseController
{
/**
* @SWG\Get(path="/station/{station_id}/listeners",
* tags={"Authenticated Endpoints"},
* tags={"Stations: Listeners"},
* description="Return detailed information about current listeners.",
* @SWG\Parameter(ref="#/parameters/station_id_required"),
* @SWG\Response(

4
app/modules/api/controllers/RequestsController.php
View File

@ -8,7 +8,7 @@ class RequestsController extends BaseController
{
/**
* @SWG\Get(path="/station/{station_id}/requests",
* tags={"Station Details"},
* tags={"Stations: Song Requests"},
* description="Return a list of requestable songs.",
* @SWG\Parameter(ref="#/parameters/station_id_required"),
* @SWG\Response(
@ -128,7 +128,7 @@ class RequestsController extends BaseController
/**
* @SWG\Post(path="/station/{station_id}/request/{request_id}",
* tags={"Station Details"},
* tags={"Stations: Song Requests"},
* description="Submit a song request.",
* @SWG\Parameter(ref="#/parameters/station_id_required"),
* @SWG\Parameter(

4
app/modules/api/controllers/StationsController.php
View File

@ -7,7 +7,7 @@ class StationsController extends BaseController
{
/**
* @SWG\Get(path="/stations",
* tags={"Station Details"},
* tags={"Stations: General"},
* description="Returns a list of stations.",
* parameters={},
* @SWG\Response(
@ -35,7 +35,7 @@ class StationsController extends BaseController
/**
* @SWG\Get(path="/station/{station_id}",
* tags={"Station Details"},
* tags={"Stations: General"},
* description="Return information about a single station.",
* @SWG\Parameter(ref="#/parameters/station_id_required"),
* @SWG\Response(

6
app/src/AzuraCast/Console/Command/GenerateApiDocs.php
View File

@ -25,7 +25,11 @@ class GenerateApiDocs extends \App\Console\Command\CommandAbstract
define('AZURACAST_VERSION', \AzuraCast\Version::getVersion());
define('SAMPLE_TIMESTAMP', rand(time() - 86400, time() + 86400));
$swagger = \Swagger\scan(APP_INCLUDE_BASE, [
$swagger = \Swagger\scan([
APP_INCLUDE_ROOT . '/swagger.php',
APP_INCLUDE_BASE . '/models/Api',
APP_INCLUDE_MODULES . '/api',
], [
'exclude' => [
'bootstrap',
'locale',

25
app/swagger.php → swagger.php
View File

@ -4,7 +4,6 @@
* schemes={"http","https"},
* consumes={"application/json"},
* produces={"application/json"},
* host="",
* basePath="/api",
* @SWG\Info(
* version=AZURACAST_VERSION,
@ -36,6 +35,15 @@
* description="This API call has no documentated response (yet)",
* )
*
* @SWG\Tag(
* name="Now Playing",
* description="Endpoints that provide full summaries of the current state of stations.",
* )
* @SWG\Tag(name="Miscellaneous")
* @SWG\Tag(name="Stations: General")
* @SWG\Tag(name="Stations: Song Requests")
* @SWG\Tag(name="Stations: Listeners")
*
* @SWG\SecurityScheme(
* securityDefinition="api_key",
* type="apiKey",
@ -43,16 +51,7 @@
* name="X-API-Key"
* )
*
* @SWG\Tag(
* name="Now Playing",
* description="Endpoints that provide full summaries of the current state of stations.",
* )
* @SWG\Tag(
* name="Station Details",
* description="Specific information on individual stations"
* )
* @SWG\Tag(
* name="Authenticated Endpoints",
* description="API calls with more detailed information, requiring specific credentialed access.",
* )
*
*
*
*/

54
web/static/api/swagger.json
View File

@ -9,7 +9,6 @@
},
"version": "0.6.0-2017.06"
},
"host": "",
"basePath": "/api",
"schemes": [
"http",
@ -59,7 +58,7 @@
"/station/{station_id}/listeners": {
"get": {
"tags": [
"Authenticated Endpoints"
"Stations: Listeners"
],
"description": "Return detailed information about current listeners.",
"parameters": [
@ -140,7 +139,7 @@
"/station/{station_id}/requests": {
"get": {
"tags": [
"Station Details"
"Stations: Song Requests"
],
"description": "Return a list of requestable songs.",
"parameters": [
@ -170,7 +169,7 @@
"/station/{station_id}/request/{request_id}": {
"post": {
"tags": [
"Station Details"
"Stations: Song Requests"
],
"description": "Submit a song request.",
"parameters": [
@ -202,7 +201,7 @@
"/stations": {
"get": {
"tags": [
"Station Details"
"Stations: General"
],
"description": "Returns a list of stations.",
"parameters": [],
@ -222,7 +221,7 @@
"/station/{station_id}": {
"get": {
"tags": [
"Station Details"
"Stations: General"
],
"description": "Return information about a single station.",
"parameters": [
@ -260,7 +259,7 @@
"connected_on": {
"description": "",
"type": "integer",
"example": 1497660417
"example": 1497656552
},
"connected_time": {
"description": "",
@ -280,7 +279,7 @@
"description": "",
"$ref": "#/definitions/Station"
},
"current_song": {
"now_playing": {
"description": "",
"$ref": "#/definitions/SongHistory"
},
@ -301,7 +300,7 @@
"enum": [
"hit",
"database",
"miss"
"station"
]
}
},
@ -312,17 +311,17 @@
"current": {
"description": "",
"type": "integer",
"example": "15"
"example": 15
},
"unique": {
"description": "",
"type": "integer",
"example": "15"
"example": 15
},
"total": {
"description": "",
"type": "integer",
"example": "20"
"example": 20
}
},
"type": "object"
@ -361,7 +360,7 @@
"played_at": {
"description": "",
"type": "integer",
"example": 1497660417
"example": 1497656552
},
"is_request": {
"description": "",
@ -425,23 +424,28 @@
"properties": {
"name": {
"description": "",
"type": "string"
"type": "string",
"example": "/radio.mp3"
},
"is_default": {
"description": "",
"type": "boolean"
"type": "boolean",
"example": true
},
"url": {
"description": "",
"type": "string"
"type": "string",
"example": "http://localhost:8000/radio.mp3"
},
"bitrate": {
"description": "",
"type": "integer"
"type": "integer",
"example": 128
},
"format": {
"description": "",
"type": "string"
"type": "string",
"example": "mp3"
}
},
"type": "object"
@ -475,7 +479,7 @@
"timestamp": {
"description": "",
"type": "integer",
"example": 1497660417
"example": 1497656552
}
},
"type": "object"
@ -569,12 +573,16 @@
"description": "Endpoints that provide full summaries of the current state of stations."
},
{
"name": "Station Details",
"description": "Specific information on individual stations"
"name": "Miscellaneous"
},
{
"name": "Authenticated Endpoints",
"description": "API calls with more detailed information, requiring specific credentialed access."
"name": "Stations: General"
},
{
"name": "Stations: Song Requests"
},
{
"name": "Stations: Listeners"
}
],
"externalDocs": {