From b214b57976228b1a8ff8ea3a3bfd0fab55f4e3cf Mon Sep 17 00:00:00 2001 From: Jannis R Date: Thu, 4 Feb 2021 19:24:13 +0100 Subject: [PATCH] =?UTF-8?q?enable=20OpenAPI=20spec,=20link=20to=20it=20?= =?UTF-8?q?=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-docs.js | 2 ++ api.js | 1 + docs/api.md | 2 ++ docs/getting-started.md | 2 +- docs/readme.md | 1 + routes/station.js | 32 +++++++++++++++++++++++ routes/stations.js | 58 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 97 insertions(+), 1 deletion(-) diff --git a/api-docs.js b/api-docs.js index 4b3047a..8bf1078 100644 --- a/api-docs.js +++ b/api-docs.js @@ -10,6 +10,8 @@ const HEAD = `\ You can just use the API without authentication. There's a [rate limit](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) of 100 request/minute (burst 200 requests/minute) set up. +[OpenAPI playground](https://petstore.swagger.io/?url=https%3A%2F%2Fv5.db.transport.rest%2F.well-known%2Fservice-desc%0A) + *Note:* For [URL-encoding](https://de.wikipedia.org/wiki/URL-Encoding), this documentation uses the \`url-encode\` tool of the [\`url-decode-encode-cli\` package](https://www.npmjs.com/package/url-decode-encode-cli). ` diff --git a/api.js b/api.js index 87bcfd5..7d11fea 100644 --- a/api.js +++ b/api.js @@ -56,6 +56,7 @@ const config = { homepage: pkg.homepage, version: pkg.version, docsLink: 'https://github.com/derhuerst/db-rest/blob/5/docs/readme.md', + openapiSpec: true, logging: true, aboutPage: false, etags: 'strong', diff --git a/docs/api.md b/docs/api.md index be40eaf..d7c5669 100644 --- a/docs/api.md +++ b/docs/api.md @@ -4,6 +4,8 @@ You can just use the API without authentication. There's a [rate limit](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) of 100 request/minute (burst 200 requests/minute) set up. +[OpenAPI playground](https://petstore.swagger.io/?url=https%3A%2F%2Fv5.db.transport.rest%2F.well-known%2Fservice-desc%0A) + *Note:* For [URL-encoding](https://de.wikipedia.org/wiki/URL-Encoding), this documentation uses the `url-encode` tool of the [`url-decode-encode-cli` package](https://www.npmjs.com/package/url-decode-encode-cli). diff --git a/docs/getting-started.md b/docs/getting-started.md index 927bf4b..c3e545e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -316,4 +316,4 @@ Note that `departure` includes the `departureDelay`, and `arrival` includes the ### 4. more features -These are the basics. Check the full [API docs](api.md) for all features! +These are the basics. Check the full [API docs](api.md) for all features or use the [OpenAPI playground](https://petstore.swagger.io/?url=https%3A%2F%2Fv5.db.transport.rest%2F.well-known%2Fservice-desc%0A) or explore the API! diff --git a/docs/readme.md b/docs/readme.md index 5103a9a..673a6cf 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -8,6 +8,7 @@ Because it wraps [an API](https://github.com/public-transport/hafas-client/blob/ - [Getting Started](getting-started.md) - [API documentation](api.md) +- [OpenAPI playground](https://petstore.swagger.io/?url=https%3A%2F%2Fv5.db.transport.rest%2F.well-known%2Fservice-desc%0A) ## Why use this API? diff --git a/routes/station.js b/routes/station.js index de4e12c..7f005c5 100644 --- a/routes/station.js +++ b/routes/station.js @@ -25,4 +25,36 @@ const stationRoute = (req, res, next) => { .catch(next) } +stationRoute.openapiPaths = { + '/stations/{id}': { + get: { + summary: 'Returns a stop/station from `db-stations`.', + description: `\ +Returns a stop/station from [\`db-stations\`](https://npmjs.com/package/db-stations).`, + parameters: [{ + name: 'id', + in: 'path', + description: 'Stop/station ID.', + required: true, + schema: { + type: 'string', + }, + }], + responses: { + '2XX': { + description: 'A stop/station, in the [`db-stations` format](https://github.com/derhuerst/db-stations/blob/master/readme.md).', + content: { + 'application/json': { + schema: { + type: 'object', // todo + }, + // todo: example(s) + }, + }, + }, + }, + }, + }, +} + module.exports = stationRoute diff --git a/routes/stations.js b/routes/stations.js index b67a15f..6a8d32f 100644 --- a/routes/stations.js +++ b/routes/stations.js @@ -109,6 +109,64 @@ const stationsRoute = (req, res, next) => { .catch(next) } +stationsRoute.openapiPaths = { + '/stations': { + get: { + summary: 'Autocompletes stops/stations by name or filters stops/stations.', + description: `\ +If the \`query\` parameter is used, it will use [\`db-stations-autocomplete\`](https://npmjs.com/package/db-stations-autocomplete) to autocomplete *Deutsche Bahn*-operated stops/stations by name. Otherwise, it will filter the stops/stations in [\`db-stations\`](https://npmjs.com/package/db-stations). + +Instead of receiving a JSON response, you can request [newline-delimited JSON](http://ndjson.org) by sending \`Accept: application/x-ndjson\`.`, + parameters: [{ + name: 'query', + in: 'query', + description: 'Find stations by name using [`db-stations-autocomplete`](https://npmjs.com/package/db-stations-autocomplete).', + schema: { + type: 'string', + }, + }, { + name: 'limit', + in: 'query', + description: '*If `query` is used:* Return at most `n` stations.', + schema: { + type: 'integer', + default: 3, + }, + }, { + name: 'fuzzy', + in: 'query', + description: '*If `query` is used:* Find stations despite typos.', + schema: { + type: 'boolean', + default: false, + }, + }, { + name: 'completion', + in: 'query', + description: '*If `query` is used:* Autocomplete stations.', + schema: { + type: 'boolean', + default: true, + }, + }], + responses: { + '2XX': { + description: 'An array of stops/stations, in the [`db-stations` format](https://github.com/derhuerst/db-stations/blob/master/readme.md).', + content: { + 'application/json': { + schema: { + type: 'array', + items: {type: 'object'}, // todo + }, + // todo: example(s) + }, + }, + }, + }, + }, + }, +} + stationsRoute.queryParameters = { query: { description: 'Find stations by name using [`db-stations-autocomplete`](https://npmjs.com/package/db-stations-autocomplete).',