add v2 swagger

Signed-off-by: Jack Ding <[email protected]>
redhat-cne · Nov 18, 2024 · 68060af · 68060af
1 parent f77bbde
commit 68060af
Show file tree

Hide file tree

Showing 4 changed files with 346 additions and 118 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,4 +17,5 @@ cover.out
 pub.json
 sub.json
 
-.idea
+.idea
+.cache
diff --git a/v2/README.md b/v2/README.md
@@ -0,0 +1,266 @@
+# Rest API
+[![go-doc](https://godoc.org/github.com/redhat-cne/rest-api?status.svg)](https://godoc.org/github.com/redhat-cne/rest-api)
+[![Go Report Card](https://goreportcard.com/badge/github.com/redhat-cne/rest-api)](https://goreportcard.com/report/github.com/redhat-cne/rest-api)
+[![LICENSE](https://img.shields.io/github/license/redhat-cne/rest-api.svg)](https://github.com/redhat-cne/rest-api/blob/main/LICENSE)
+
+Available Routes
+
+```html
+
+POST /api/ocloudNotifications/v2/subscriptions
+GET /api/ocloudNotifications/v2/subscriptions
+GET /api/ocloudNotifications/v2/subscriptions/{subscription_id}
+DELETE /api/ocloudNotifications/v2/subscriptions/{subscription_id}
+GET api/ocloudnotifications/v2/{resource_address}/CurrentState
+GET /api/ocloudNotifications/v2/health
+GET /api/ocloudNotifications/v2/publishers
+DELETE /api/ocloudNotifications/v2/subscriptions
+```
+
+## Pub/Sub Rest API
+
+Rest API spec .
+
+### Version: 1.0.0
+
+
+### /publishers/
+
+#### POST
+##### Summary
+
+Creates a new publisher.
+
+##### Description
+
+If publisher creation is success(or if already exists), publisher will be returned with Created (201).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| publisher | body | publisher to add to the list of pub | [PubSub](#pubsub) |
+
+##### Responses
+
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 201 | publisher/subscription data model | [PubSub](#pubsub) |
+| 400 | Error Bad Request | object |
+
+### /subscriptions/
+
+#### POST
+##### Summary
+
+Creates a new subscription.
+
+##### Description
+
+If subscription creation is success(or if already exists), subscription will be returned with Created (201).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| subscription | body | subscription to add to the list of subscriptions | yes | [PubSub](#pubsub) |
+
+##### Responses
+
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 201 | publisher/subscription data model | [PubSub](#pubsub) |
+| 400 | Error Bad Request | object |
+
+
+
+### /create/event/
+
+#### POST
+##### Summary
+
+Creates a new event.
+
+##### Description
+
+If publisher is present for the event, then event creation is success and be returned with Accepted (202).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| event | body | event along with publisher id | Yes | [Event](#event) |
+
+##### Responses
+
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 202 | Accepted | object |
+| 400 | Error Bad Request | object |
+
+### /subscriptions/status/{subscriptionid}
+
+#### PUT
+##### Summary
+
+Creates a new status ping request.
+
+##### Description
+
+If a subscription is present for the request, then status request is success and be returned with Accepted (202).
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| subscriptionid | request  | subscription id | Yes |  |
+
+##### Responses
+
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 202 | Accepted | object |
+| 400 | Error Bad Request | object |
+
+### Models
+
+#### Data
+
+Data ... cloud native events' data Json payload is as follows,
+```json
+
+{
+"version": "v1.0",
+"values": [{
+"resource": "/cluster/node/ptp",
+"dataType": "notification",
+"valueType": "enumeration",
+"value": "ACQUIRING-SYNC"
+}, {
+"resource": "/cluster/node/clock",
+"dataType": "metric",
+"valueType": "decimal64.3",
+"value": 100.3
+}]
+}
+```
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| values | [ [DataValue](#datavalue) ] |  | Yes |
+| version | string |  | Yes |
+
+#### DataType
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| DataType | string |  | Yes |
+
+#### DataValue
+
+DataValue Json payload is as follows,
+```json
+
+{
+"resource": "/cluster/node/ptp",
+"dataType": "notification",
+"valueType": "enumeration",
+"value": "ACQUIRING-SYNC"
+}
+```
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| dataType | [DataType](#datatype) |  | yes |
+| resource | string |  | yes |
+| value | object |  | yes |
+| valueType | [ValueType](#valuetype) |  | yes |
+
+#### Event
+
+Event Json  payload is as follows,
+```json
+
+{
+"id": "5ce55d17-9234-4fee-a589-d0f10cb32b8e",
+"type": "event.synchronization-state-chang",
+"time": "2021-02-05T17:31:00Z",
+"data": {
+"version": "v1.0",
+"values": [{
+"resource": "/cluster/node/ptp",
+"dataType": "notification",
+"valueType": "enumeration",
+"value": "ACQUIRING-SYNC"
+}, {
+"resource": "/cluster/node/clock",
+"dataType": "metric",
+"valueType": "decimal64.3",
+"value": 100.3
+}]
+}
+}
+```
+Event request model
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [Data](#data) |  | yes |
+| dataContentType | string | DataContentType - the Data content type +required | yes |
+| dataSchema | [URI](#uri) |  | No |
+| id | string | ID of the event; must be non-empty and unique within the scope of the producer. +required | yes |
+| time | [Timestamp](#timestamp) |  | yes |
+| type | string | Type - The type of the occurrence which has happened. +required | yes |
+
+#### PubSub
+PubSub Json request payload is as follows,
+```json
+
+{
+"id": "789be75d-7ac3-472e-bbbc-6d62878aad4a",
+"endpointUri": "http://localhost:9090/ack/event",
+"uriLocation":  "<http://localhost:8080/api/ocloudNotifications/v2/publishers/{publisherid>}",
+"resource":  "/east-edge-10/vdu3/o-ran-sync/sync-group/sync-status/sync-state"
+}
+```
+PubSub request model
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| endpointUri | [URI](#uri) |  | yes |
+| resource | string | Resource - The type of the Resource. +required | yes |
+
+
+#### Timestamp
+
+Timestamp wraps time.Time to normalize the time layout to RFC3339. It is
+intended to enforce compliance with the Cloud Native events spec for their
+definition of Timestamp. Custom marshal methods are implemented to ensure
+the outbound Timestamp is a string in the RFC3339 layout.
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| Timestamp | object | Timestamp wraps time.Time to normalize the time layout to RFC3339. It is intended to enforce compliance with the Cloud Native events spec for their definition of Timestamp. Custom marshal methods are implemented to ensure the outbound Timestamp is a string in the RFC3339 layout. |  |
+
+#### URI
+
+URI is a wrapper to url.URL. It is intended to enforce compliance with
+the Cloud Native Events spec for their definition of URI. Custom
+marshal methods are implemented to ensure the outbound URI object
+is a flat string.
+
+
+#### ValueType
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| ValueType | ENUM | ENUMERATION,DECIMAL | yes |
+
+
+## Collecting metrics with Prometheus
+Cloud native events rest API comes with following metrics collectors .
+1. Number of events published by the rest api.
+2. Number of active subscriptions.
+3. Number of active publishers.
+
+[Metrics details ](docs/metrics.md)
diff --git a/v2/server.go b/v2/server.go
@@ -20,8 +20,8 @@
 //
 //	Schemes: http, https
 //	Host: localhost:8089
-//	basePath: /api/ocloudNotifications/v1
-//	Version: 1.0.0
+//	BasePath: /api/ocloudNotifications/v2
+//	Version: 2.0.0
 //	Contact: Aneesh Puttur<[email protected]>
 //
 //	Consumes:
@@ -44,7 +44,6 @@ import (
 	"github.com/gorilla/mux"
 	"github.com/redhat-cne/sdk-go/pkg/channel"
 	"github.com/redhat-cne/sdk-go/pkg/event"
-	"github.com/redhat-cne/sdk-go/pkg/pubsub"
 	"github.com/redhat-cne/sdk-go/pkg/types"
 	pubsubv1 "github.com/redhat-cne/sdk-go/v1/pubsub"
 	subscriberApi "github.com/redhat-cne/sdk-go/v1/subscriber"
@@ -95,10 +94,32 @@ type Server struct {
 }
 
 // publisher/subscription data model
+// SubscriptionInfo defines data types used for subscription.
+type SubscriptionInfo struct { //nolint:deadcode,unused
+	// Identifier for the created subscription resource.
+	// +required
+	ID string `json:"SubscriptionId" omit:"empty"`
+	// A URI describing the call back address.
+	// +required
+	EndPointURI string `json:"EndpointUri" example:"http://localhost:8080/resourcestatus/ptp" omit:"empty"`
+	// A URI describing the publisher/subscription get link.
+	URILocation string `json:"UriLocation" omit:"empty"`
+	// The resource address specifies the Event Producer with a hierarchical path.
+	// Format /{clusterName}/{siteName}(/optional/hierarchy/..)/{nodeName}/{(/optional/hierarchy)/resource}
+	// +required
+	Resource string `json:"ResourceAddress" example:"/east-edge-10/vdu3/o-ran-sync/sync-group/sync-status/sync-state"`
+}
+
 // swagger:response pubSubResp
 type swaggPubSubRes struct { //nolint:deadcode,unused
 	// in:body
-	Body pubsub.PubSub
+	Body SubscriptionInfo
+}
+
+// swagger:response publishers
+type swaggPubSubResList struct { //nolint:deadcode,unused
+	// in:body
+	Body []SubscriptionInfo
 }
 
 // PubSub request model
@@ -243,7 +264,7 @@ func (s *Server) Start() {
 	api.HandleFunc("/subscriptions", s.createSubscription).Methods(http.MethodPost)
 
 	//createPublisher create publisher and send it to a channel that is shared by middleware to process
-	// swagger:operation POST /publishers/ publishers createPublisher
+	// internal:operation POST /publishers/ publishers createPublisher
 	// ---
 	// summary: Creates a new publisher.
 	// description: If publisher creation is success(or if already exists), publisher will be returned with Created (201).
@@ -252,7 +273,7 @@ func (s *Server) Start() {
 	//   description: publisher to add to the list of publishers
 	//   in: body
 	//   schema:
-	//      "$ref": "#/definitions/PubSub"
+	//      "$ref": "#/definitions/SubscriptionInfo"
 	// responses:
 	//   "201":
 	//     "$ref": "#/responses/pubSubResp"
@@ -265,18 +286,23 @@ func (s *Server) Start() {
 			See note below.
 		404 Subscription resources are not available (not created).
 	*/
+	// swagger:route GET /subscriptions
+	// Get a list of subscription object(s) and their associated properties.
+	// responses:
+	//   200: Returns the subscription resources and their associated properties that already exist.
+	//   400: Bad request by the client.
 	api.HandleFunc("/subscriptions", s.getSubscriptions).Methods(http.MethodGet)
 	//publishers create publisher and send it to a channel that is shared by middleware to process
 	// swagger:operation GET /publishers/ publishers getPublishers
 	// ---
 	// summary: Get publishers.
-	// description: If publisher creation is success(or if already exists), publisher will be returned with Created (201).
+	// description: Returns a list of publisher details for the cluster node.
 	// parameters:
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/publishers"
 	//   "404":
-	//     "$ref": "#/responses/notFound"
+	//     "$ref": "#/responses/notFoundReq"
 	api.HandleFunc("/publishers", s.getPublishers).Methods(http.MethodGet)
 	// 200 and 404
 	api.HandleFunc("/subscriptions/{subscriptionid}", s.getSubscriptionByID).Methods(http.MethodGet)
@@ -289,7 +315,8 @@ func (s *Server) Start() {
 	api.HandleFunc("/publishers", s.deleteAllPublishers).Methods(http.MethodDelete)
 
 	//pingForSubscribedEventStatus pings for event status  if the publisher  has capability to push event on demand
-	// swagger:operation POST /subscriptions/status subscriptions pingForSubscribedEventStatus
+	// this API is internal
+	// operation POST /subscriptions/status subscriptions pingForSubscribedEventStatus
 	// ---
 	// summary: Get status of publishing events.
 	// description: If publisher status ping is success, call  will be returned with status accepted.
@@ -313,7 +340,7 @@ func (s *Server) Start() {
 	api.HandleFunc("/log", s.logEvent).Methods(http.MethodPost)
 
 	//publishEvent create event and send it to a channel that is shared by middleware to process
-	// swagger:operation POST /create/event/ event publishEvent
+	// this API is internal
 	// ---
 	// summary: Creates a new event.
 	// description: If publisher is present for the event, then event creation is success and be returned with Accepted (202).