enable OpenAPI spec, link to it 📝

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).
 `
 

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',

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).
 
 

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!

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?
 

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

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).',