Live Data

See the live docs at https://podcastindex-org.github.io/docs-api/

Introduction

This project contains the files for describing the PodcastIndex.org API using the openapi syntax.

The redocly/openapi-cli Node package is used to compile the separate files in to a single master file. This master file can be used in many tools.

The RapiDoc software is used to generate the document webpage.

Installation

No items are installed globally. Run yarn to install the Node required packages.

Available Scripts

In the project directory, you can run:

`yarn preview`

Starts the redoc preview server. Open http://localhost:8080 to view it in the browser.

`yarn build`

Runs bundle_json, bundle_yaml

`yarn bundle_json`

Generates the master openapi file pi_api.json in the docs folder.

The pi_api.json and pi_api.yaml contain the same content just shown in different formats.

`yarn bundle_yaml`

Generates the master openapi file pi_api.yaml in the docs folder.

The pi_api.json and pi_api.yaml contain the same content just shown in different formats.

`yarn lint`

Run the redoc linter on the source yaml files.

`yarn reload`

Starts a LiveReload file watcher.

Install a compatible browser extension and connect it to the livereload instance.

Pages connected to the file watcher will reload 2 seconds after the file changes. The 2 second delay gives the openapi preview script time to generate the new api files.

`yarn server`

Create a simple server in the docs folder to serve the release files.

Folder Structure

`api_src`

This folder contains the source yaml files for describing the API. The root file is root.yaml.

See the openapi Specification for details on the format. Additional specification details from Swagger and OpenAPI GitHub.

THe remaining folders follow the structure suggested by create-openapi-repo.

`paths`

The folder structure should follow the paths in the API requests where the file is the last value in the request URL path.

See additional suggestions for the structure from redoc in the create-openapi-repo project.

`components`

In general, a folder exists for each object type in the API yaml document. A block that is used in many files should have a separate yaml file created and be referenced from the files where it is used.

callbacks - reusable Callback Objects
examples - reusable Example Objects
headers - reusable Header Objects
links - reusable Link Objects
parameters - reusable Parameter Objects
requestBodies - reusable Request Body Objects
responses - reusable Response Objects
schemas - reusable Schema Objects
securitySchemes - reusable Security Scheme Objects

`docs`

Source directory for site source files. This folder should be deployed to the server.

The master api files and images are in the root directory. The root index.html uses the RapiDoc UI.

The template.html file is the necessary template file for the redoc preview generated with yarn preview is also in this folder.

johnspurlock / docs-api