From ca62cc8f2f1d72760595e1502ad0a5c4304ea27a Mon Sep 17 00:00:00 2001
From: Adrian Cole <acole@pivotal.io>
Date: Mon, 14 Aug 2017 13:58:56 +0800
Subject: [PATCH] Adds openapi spec for POST /api/v2/spans including the json
 format

See #1499 for the description of this format
---
 zipkin2-api.yaml | 124 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 zipkin2-api.yaml

diff --git a/zipkin2-api.yaml b/zipkin2-api.yaml
new file mode 100644
index 0000000..1426046
--- /dev/null
+++ b/zipkin2-api.yaml
@@ -0,0 +1,124 @@
+swagger: "2.0"
+info:
+  version: "1.0.0"
+  title: Zipkin API
+  description: |
+    Zipkin's v2 api currently includes a POST endpoint that can receive spans.
+host: localhost:9411
+basePath: /api/v2
+schemes:
+  - http
+  - https
+consumes:
+  - application/json
+paths:
+  /spans:
+    post:
+      description: |
+          Uploads a list of spans encoded per content-type, for example json.
+      consumes:
+        - application/json
+      produces: []
+      parameters:
+        - name: spans
+          in: body
+          description: A list of spans that belong to any trace.
+          required: true
+          schema:
+            $ref: "#/definitions/ListOfSpans"
+      responses:
+        202:
+          description: Accepted
+definitions:
+  Endpoint:
+    type: object
+    title: Endpoint
+    properties:
+      serviceName:
+        type: string
+        description: 'Classifier of this endpoint in lowercase, such as "acme-frontend"'
+      ipv4:
+        type: string
+        description: 'The text representation of a IPv4 address associated with this endpoint. Ex. 192.168.99.100'
+      ipv6:
+        type: string
+        description: 'The text representation of a IPv6 address associated with this endpoint. Ex. 2001:db8::c001'
+      port:
+        type: integer
+  Annotation:
+    title: Annotation
+    type: object
+    properties:
+      timestamp:
+        type: integer
+      value:
+        type: string
+  Tags:
+    type: object
+    title: Tags
+    additionalProperties:
+      type: string
+  ListOfSpans:
+    title: ListOfSpans
+    description: 'A list of spans with possibly different trace ids, in no particular order'
+    type: array
+    items:
+      $ref: "#/definitions/Span"
+  Span:
+    title: Span
+    type: object
+    properties:
+      traceId:
+        type: string
+        maxLength: 32
+        minLength: 16
+        description: 'Randomly generated, unique for a trace, set on all spans within it. 8-byte or 16-byte identifier respectively encoded as 16 or 32 lowercase hex characters.'
+      name:
+        type: string
+        description: 'The logical operation this span represents in lowercase (e.g. rpc method)'
+      parentId:
+        type: string
+        maxLength: 16
+        minLength: 16
+        description: 'Parent span id. 8-byte identifier encoded as 16 lowercase hex characters. Can be ommitted or set to nil if span is the root span of a trace.'
+      id:
+        type: string
+        maxLength: 16
+        minLength: 16
+        description: 'Id of current span, unique in context of traceId. 8-byte identifier encoded as 16 lowercase hex characters.'
+      kind:
+        type: string
+        enum:
+          - CLIENT
+          - SERVER
+          - PRODUCER
+          - CONSUMER
+        description: 'Indicates the primary span type.'
+      timestamp:
+        type: integer
+        format: int64
+        description: 'Epoch **microseconds** of the start of this span, possibly absent if this an incomplete span.'
+      duration:
+        type: integer
+        format: int64
+        description: 'Duration in **microseconds** of the critical path, if known. Durations of less than one are rounded up.'
+      debug:
+        type: boolean
+        description: 'Indicator whether this trace was sampled from standard traffic or forced. Usually coupled to the X-B3-Flags header, which when set to true is a request to store this span even if it overrides sampling policy.'
+      shared:
+        type: boolean
+        description: 'True if we are contributing to a span started by another tracer (ex on a different host).'
+      localEndpoint:
+        $ref: "#/definitions/Endpoint"
+        description: 'The host that recorded this span, primarily for query by service name.'
+      remoteEndpoint:
+        $ref: "#/definitions/Endpoint"
+        description: 'When an RPC (or messaging) span, indicates the other side of the connection.'
+      annotations:
+        type: array
+        items:
+          $ref: '#/definitions/Annotation'
+        description: 'Associates an event that explains latency with the time it happened.'
+      tags:
+        $ref: '#/definitions/Tags'
+        description: 'Tags give your span context for search, viewing and analysis.'