Cloud Configurations Repository Wiki

How to Contribute

Anyone is welcome to contribute to this project. Be sure to follow the guidelines below and get started!

Folder Structure

The following diagram displays how a developer should set up their API folder structure:

APIs/
├─ API_NAME/
│  ├─ master.yaml
│  ├─ models/
│  │  ├─ someModel1.yaml
│  ├─ paths/
│  │  ├─ somePath1.yaml
CommonFragments/
CommonModels/

Note that master.yaml contains the info about the API, specific components and the path definitions. An example can be found below:

openapi: 3.0.3
info: "Information about your API, what it does and how it works"
servers:
	- url: https://development.service.example.com/
   	  description: "Development server, breaking changes are often made here"
    - url: https://staging.service.example.com/
      description: "Staging server, breaking changes should rarely happen here"
    - url: https://service.example.com/
      description: "Production server, breaking changes should never happen here"
paths:
	/path/resource:
    	- $ref: ./paths/path-resource.yaml
    /path/something:
    	- $ref: ./paths/path-something.yaml
components:
	someComponent ...
security:
	someSecurity ...
tags:
	someTags ...
 externalDocs:
 	description: Find more info here
    url: https://docs.example.com/someServiceDoc.html

Common Fragments

Common fragments are very small blobs of yaml code that can be shared amongst any services. For example, it is standard that a username has a minimum and maximum length. Therefore, we can create a fragment that we can reuse across all yaml files.

Common Models

Common models are yaml object files that contain code that is shared amongst any services. An example of this is the standard response one might get from the health and version api. Other examples are general HTTP error codes