Skip to content

Latest commit

 

History

History
86 lines (67 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

86 lines (67 loc) · 3.83 KB
Raw

Contributing

We welcome and encourage contributions from the community. Keep in mind that this spec describes the current production API so changes must reflect actual behavior of the API.

Development

Prerequisites

The following tools are required

  • Git: Interact with the source code
  • Make: Used to maintain common commands for use in the development environment or build system
  • Node.js: For managing dependencies and running tools
  • Docker: For running tools in isolation

Installation

Once the prerequisites are installed, the source can be downloaded and the dependencies can be installed:

git clone git@github.com:digitalocean/apiv2-openapi.git
cd apiv2-openapi
make preview

The make preview command starts a local web server with the rendered API docs and watches the source files for changes. The rendered docs can be viewed in the browser at the address listed in the startup output (http://localhost:8080).

Tooling

The tooling chosen supports either authoring, validation, testing, or publishing. Respective Make target

  • Spectral: JSON/YAML linter with support for OpenAPI v3, custom rules, built-in functions, and custom functions
  • Prism: Set of packages to API mocking. Also provides a live validation proxy.
  • OpenAPI CLI: OpenAPI CLI toolbox with rich validation and bundling features.

In addition, the following tools are leveraged to facilitate authoring the spec.

Visual Studio Code Extensions

These are useful extensions when choosing to author OpenAPI spec using Visual Studio Code.

  • Spectral: View linting violations inline
  • OpenAPI Preview: Preview the API spec in SwaggerUI within the editor
  • YAML: Base YAML syntax validation
  • Docker: View/Manage containers within the editor sidebar

Repository Structure

These files and directories contain the API specification broken down to

├── specification
│   ├── DigitalOcean-public.v2.yaml:  Root YAML spec file
│   ├── resources/:  Contains directories for each top-level resource (referenced from the `paths` section in the root file)
│   │   ├── <resource_name>/:  Resource specific content
│   │   │   ├── models/:  Request and response models 
│   │   │   ├── responses/:  Response definition to reference from respective request definition file
│   │   │   ├── <request_definition>.yml:  Request definition to be referenced from respective path section in root file
│   ├── shared/:  Generalized definitions referenced across the API spec
│   │   ├── headers.yml:  Header definition (separated by named keys)
│   │   ├── attributes/:  Collection of common attributes
│   │   │   ├── <attribute_name>.yml:  Individual attribute definition
│   │   ├── models/:  Collection of common models
│   │   │   ├── <model_name>.yml:  Individual model definition
│   │   ├── parameters.yml:  Parameter definition (separated by named keys)
│   │   └── responses/:  Response definitions
│   │   │   ├── <response_name>.yml:  Individual response definition
│   └── tests/:  Placeholder directory for test generation and output