update conformity to OpenAPI spec

versions/master/README.md

@@ -13,7 +13,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 There are specific concepts that all participants in this open API must support in order to make interaction possible. Each of these concepts should be driven by factory configurations or by on-site configurations made by the customer or a professional integrator.  
 
-Compliance with the Open-Agtech API requires adherence to the OpenAPI Specification (currently [3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md)). In addition, there are several principles that account for the needs of our industry.
+Compliance with the Open-Agtech API requires adherence to the OpenAPI Specification (currently [3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md)).
+
+# OpenAPI Specification
+
+For convenience, we have included some of the more important and relevant concepts of the OpenAPI spec. While the complete spec is not located here, these concepts will provide a foundation for building a compliant API.
+
+### Open AgTech API Document
+
+The Open AgTech API Document describes the structure of a compliant API. Documents MUST be in YAML or JSON format and SHOULD be accessible to consumers of the API. You can read more about the structure of the document at the [Open API Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#document-structure), or see examples (**TODO: EXAMPLES**)
+
+In addition, there are several principles that account for the needs of our industry.
 
 # URL construction
 

versions/master/examples/documents/lights.yaml

@@ -0,0 +1,247 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: FarmCo Lights
+  license:
+    name: MIT
+servers:
+  - url: http://farmco.example.com/agroapi/v1
+paths:
+  /light_sensors:
+    get:
+      description: Returns all sensors from the system that the user has access to
+      responses:
+        '200':
+          description: A list of sensors.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Sensor'
+  /light_sensors/{sensorId}:
+    get:
+     summary: Info for a specific sensor
+     operationId: showSensorById
+     tags:
+       - sensors
+     parameters:
+       - name: sensorId
+         in: path
+         required: true
+         description: The id of the sensor to retrieve
+         schema:
+           type: string
+     responses:
+       '200':
+         description: Expected response to a valid request
+         content:
+           application/json:
+             schema:
+               type: array
+               items:
+                 $ref: "#/components/schemas/Sensors"
+       default:
+         description: unexpected error
+         content:
+           application/json:
+             schema:
+               $ref: "#/components/schemas/Error"
+
+  /light_sensors/{sensorId}/measurements:
+    get:
+      description: Returns spectrum measurements from a specific sensor
+      parameters:
+        - name: type
+          in: query
+          required: false
+          description: ppf or ppfd, defaults to ppfd
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A list of measurements
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/SpectrumMeasurement'
+
+  /zone/{zoneId}/sensors:
+    get:
+      description: Returns all sensors from a zone
+      responses:
+        '200':
+          description: A list of sensors.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Sensor'
+
+  /light_sensors:
+    get:
+      description: Returns all sensors from a zone
+      responses:
+        '200':
+          description: A list of sensors.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Sensor'
+
+  /light_fixtures:
+    get:
+      description: Returns all fixtures that a user has access to
+      responses:
+        '200':
+          description: A list of fixtures.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Fixture'
+
+  /light_fixtures/{fixtureId}:
+    get:
+      summary: Info for a specific fixture
+      operationId: showFixtureById
+      tags:
+        - fixtures
+      parameters:
+        - name: fixtureId
+          in: path
+          required: true
+          description: The id of the fixture to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Fixture"
+
+  /light_fixtures/{fixtureId}/light_channels:
+    get:
+      description: Returns all channels from a fixture
+      responses:
+        '200':
+          description: A list of channels.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Channel'
+
+components:
+  schemas:
+    Sensor:
+      type: object
+      required:
+      - id
+      properties:
+        name:
+          type: string
+        info:
+          type: string
+        version:
+          type: string
+        location:
+          ***TODO: LOCATION FORMAT*** general.md#location-data
+        info:
+          ***TODO: INFO FORMAT*** general.md#info-data
+        age:
+          type: integer
+          format: int32
+          minimum: 0
+    Sensors:
+      type: array
+      items:
+        $ref: "#components/schemas/Sensor"
+    Measurement:
+      type: object
+      required:
+      - id
+      properties:
+        id:
+          description: Unique id of the device
+          type: string
+        timestamp:
+          description: UTC timestamp of the measurement
+          type: string
+        red:
+          description: Level of red spectrum light
+          type: string
+        blue:
+          description: Level of blue spectrum light
+          type: string
+        green:
+          description: Level of green spectrum light
+          type: string
+        uv:
+          description: Level of ultraviolet light
+          type: string
+        infrared:
+          description: Level of infrared light
+          type: string
+        par:
+          description: Level of absorbable light
+          type: string
+        light:
+          description: Level of all spectrums of light
+          type: string
+    Measurements:
+      type: array
+      items:
+        $ref: "#components/schemas/Measurement"
+    Fixture:
+      type: object
+      required:
+      - id
+      - status
+      properties:
+        id:
+          description: Unique id of the fixture
+          type: string
+        name:
+          type: string
+        status:
+          description: The active state of the light ('on' or 'off')
+          type: string
+    Fixtures:
+      type: array
+      items:
+        $ref: "#components/schemas/Fixture"
+    Channel:
+      type: object
+      required:
+      - id
+      properties:
+        id:
+          description: Unique id of the channel
+        lo-color:
+          description: Lower boundary of the frequency range for a color channel
+          format: ***TODO FORMAT nm***
+        hi-color:
+          description: Upper boundary of the frequency range for a color channel
+          format: ***TODO FORMAT nm***
+        cct:
+          description: Color temperature for a white channel
+          format: ***TODO FORMAT K (Kelvin)***
+        intensity:
+          description: Light intensity
+          format: ***TODO FORMAT %***
+    Channels:
+      type: array
+      items:
+        $ref: "#components/schemas/Channel"