Introduction

The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Specification

Format

We can define a Swagger specification document by JSON or YAML

Swagger Object

• swagger: Required. Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be "2.0".
• host: The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. The host does not support path templating. Ex:

host: '11.11.254.102:8082'

• basePath: The base path on which the API is served, which is relative to the host Ex: If the API place in root of host

basePath: /

• schemes: The transfer protocol of the API. Values MUST be from the list: "http", "https", "ws", "wss".
• paths: Required. The available paths and operations for the API. Each path can be defined methods:
  • get
  • post
  • delete
  • put
• definitions: An object to hold data types produced and consumed by operations.
• tags: A list of tags used by the specification with additional metadata.

Read more: http://swagger.io/specification/#swaggerObject

Editor

http://editor.swagger.io/#!/

We can test by send request directly through output of the Swagger specification on editor

Sample Specification:

swagger: '2.0'
info:
  description: Confluent Kafka REST proxy
  version: 1.0.0
  title: Kafka REST proxy
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: '11.11.254.102:8082'
basePath: /
schemes:
  - http
tags:
  - name: topic
    description: Topic APIs
paths:
  /topics:
    get:
      tags:
        - topic
      description: Get a list of Kafka topics.
      operationId: getTopics
      produces:
        - application/json
      responses:
        '200':
          description: List of topic names
          schema:
            type: array
            items:
              type: string
  '/topics/{topic_name}':
    get:
      tags:
        - topic
      description: Get metadata about a specific topic.
      operationId: getTopicMetadata
      produces:
        - application/json
      parameters:
        - name: topic_name
          in: path
          description: Name of the topic to get metadata about
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/Topic'
        '404':
          description: Topic not found
definitions:
  Topic:
    description: The topics resource provides information about the topics in your Kafka cluster and their current state
    type: object
    properties:
      name:
        type: string
        description: Name of the topic
      configs:
        type: string
        description: Per-topic configuration overrides
      partitions:
        type: array
        description: List of partitions for this topic
        items:
          $ref: '#/definitions/Partition'
  Partition:
    description: The partitions resource provides per-partition metadata, including the current leaders and replicas for each partition
    type: object
    properties:
      partition:
        type: integer
        description: ID of the partition
      leader:
        type: integer
        description: Broker ID of the leader for this partition

Output javascript src code

/api
      TopicApi.js (topic tags)
      * getTopics method (determined by operationId)
      * getTopicMetadata
/model
      Topic.js (defined in definitions)
      Partition.js
/test (templated test cases for the api and model) ApiClient.js
index.html
index.js

Notes: Test folder contain template test cases as a starting point for testing the API. Run the test: npm test

Commands

• Code location: OceanaAnalytics\Angular-D3-Cometd\Oceanalytics\Confluent Kafka REST Proxy

• Generate JavaScript files:
  ../../Tools/swagger-codegen-cli-2.2.2.jar generate -i kafka_rest_proxy.yaml -o javascript -l javascript

• Generate JavaScript for angular files:
  ../../Tools/swagger-codegen-cli-2.2.2.jar generate -i kafka_rest_proxy.yaml -o angular-l javascript-closure-angular

• Generate Typescript angular2 files:
  ../../Tools/swagger-codegen-cli-2.2.2.jar generate -i kafka_rest_proxy.yaml -o typescript -l typescript-angular2