feat: Adds OpenAPI spec

Signed-off-by: Andrii Soluk <[email protected]>

.gitignore

@@ -32,3 +32,6 @@ coverage.txt
 node_modules
 /dist
 build
+
+deployments/keys
+deployments/demo/openapi/specs

Makefile

@@ -6,6 +6,10 @@
 GOBIN_PATH             = $(abspath .)/build/bin
 ARIES_AGENT_REST_PATH=cmd/agent-rest
 ARIES_AGENT_MOBILE_PATH=cmd/agent-mobile
+PROJECT_ROOT = github.com/trustbloc/agent-sdk
+OPENAPI_SPEC_PATH=build/rest/openapi/spec
+OPENAPI_DOCKER_IMG=quay.io/goswagger/swagger
+OPENAPI_DOCKER_IMG_VERSION=v0.23.0
 
 # Namespace for the agent images
 DOCKER_OUTPUT_NS   ?= docker.pkg.github.com
@@ -68,12 +72,45 @@ depend:
 	@mkdir -p ./build/bin
 	GO111MODULE=off GOBIN=$(GOBIN_PATH) go get github.com/agnivade/wasmbrowsertest
 
-.PHONY: clean
-clean: clean-build
+.PHONY: generate-openapi-spec
+generate-openapi-spec: clean
+	@echo "Generating and validating controller API specifications using Open API"
+	@mkdir -p build/rest/openapi/spec
+	@SPEC_LOC=${OPENAPI_SPEC_PATH}  \
+	DOCKER_IMAGE=$(OPENAPI_DOCKER_IMG) DOCKER_IMAGE_VERSION=$(OPENAPI_DOCKER_IMG_VERSION)  \
+	scripts/generate-openapi-spec.sh
+
+.PHONY: generate-openapi-demo-specs
+generate-openapi-demo-specs: clean generate-openapi-spec agent-rest-docker
+	@echo "Generate demo agent rest controller API specifications using Open API"
+	@SPEC_PATH=${OPENAPI_SPEC_PATH} OPENAPI_DEMO_PATH=deployments/demo/openapi \
+    	DOCKER_IMAGE=$(OPENAPI_DOCKER_IMG) DOCKER_IMAGE_VERSION=$(OPENAPI_DOCKER_IMG_VERSION)  \
+    	scripts/generate-openapi-demo-specs.sh
+
+generate-test-keys: clean
+	@mkdir -p -p deployments/keys/tls
+	@docker run -i --rm \
+		-v $(abspath .):/opt/go/src/$(PROJECT_ROOT) \
+		--entrypoint "/opt/go/src/$(PROJECT_ROOT)/scripts/generate_test_keys.sh" \
+		frapsoft/openssl
+
+.PHONY: run-openapi-demo
+run-openapi-demo: generate-test-keys generate-openapi-demo-specs agent-rest-docker
+	@echo "Starting demo agent rest containers ..."
+	@DEMO_COMPOSE_PATH=deployments/demo/openapi SIDETREE_COMPOSE_PATH=deployments/sidetree-mock AGENT_REST_COMPOSE_PATH=deployments/agent-rest  \
+        scripts/run-openapi-demo.sh
+
+.PHONY: stop-openapi-demo
+stop-openapi-demo:
+	@echo "Stopping demo agent rest containers ..."
+	@DEMO_COMPOSE_PATH=deployments/demo/openapi SIDETREE_COMPOSE_PATH=deployments/sidetree-mock AGENT_REST_COMPOSE_PATH=deployments/agent-rest  \
+        DEMO_COMPOSE_OP=down scripts/run-openapi-demo.sh
 
-.PHONY: clean-build
-clean-build:
+.PHONY: clean
+clean:
 	@rm -Rf ./build
 	@rm -Rf $(ARIES_AGENT_MOBILE_PATH)/build
 	@rm -Rf ./cmd/agent-js-worker/node_modules
-	@rm -Rf ./cmd/agent-js-worker/dist
+	@rm -Rf ./cmd/agent-js-worker/dist
+	@rm -Rf ./deployments/keys/tls
+	@rm -Rf ./deployments/demo/openapi/specs

cmd/agent-rest/main.go

@@ -4,7 +4,7 @@ Copyright SecureKey Technologies Inc. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
 */
 
-// Package aries-agent-rest (Aries Agent REST Server) of aries-framework-go.
+// Package agent-rest (Agent SDK REST Server) of trustbloc/agent-sdk.
 //
 //
 // Terms Of Service:
@@ -33,13 +33,13 @@ import (
 // This is an application which starts Aries agent controller API on given port.
 func main() {
 	rootCmd := &cobra.Command{
-		Use: "aries-agent-rest",
+		Use: "agent-rest",
 		Run: func(cmd *cobra.Command, args []string) {
 			cmd.HelpFunc()(cmd, args)
 		},
 	}
 
-	logger := log.New("aries-framework/agent-rest")
+	logger := log.New("agent-sdk/agent-rest")
 
 	startCmd, err := startcmd.Cmd(&startcmd.HTTPServer{})
 	if err != nil {

cmd/agent-rest/startcmd/start.go

@@ -203,7 +203,7 @@ const (
 
 var (
 	errMissingHost = errors.New("host not provided")
-	logger         = log.New("aries-framework/agent-rest")
+	logger         = log.New("agent-sdk/agent-rest")
 )
 
 type agentParameters struct {
@@ -323,7 +323,7 @@ func createStartCMD(server server) *cobra.Command { //nolint: funlen, gocyclo, g
 				return err
 			}
 
-			webhookURLs, err := getUserSetVars(cmd, agentWebhookFlagName, agentWebhookEnvKey, autoAccept)
+			webhookURLs, err := getUserSetVars(cmd, agentWebhookFlagName, agentWebhookEnvKey, true)
 			if err != nil {
 				return err
 			}

cmd/agent-rest/startcmd/start_test.go

@@ -376,9 +376,7 @@ func TestStartCmdWithoutWebhookURL(t *testing.T) {
 	}
 	startCmd.SetArgs(args)
 
-	err = startCmd.Execute()
-	require.Error(t, err)
-	require.Contains(t, err.Error(), "webhook-url not set")
+	require.NoError(t, startCmd.Execute())
 }
 
 func TestStartCmdWithLogLevel(t *testing.T) {
@@ -893,6 +891,11 @@ func TestCreateVDRs(t *testing.T) {
 	}
 }
 
+func TestCmd_getUserSetVars(t *testing.T) {
+	_, err := getUserSetVars(&cobra.Command{}, "unknown", "unknown", false)
+	require.EqualError(t, err, " unknown not set. It must be set via either command line or environment variable")
+}
+
 func waitForServerToStart(t *testing.T, host, inboundHost string) {
 	if err := listenFor(host); err != nil {
 		t.Fatal(err)

deployments/agent-rest/.env

@@ -0,0 +1,44 @@
+#
+# Copyright SecureKey Technologies Inc. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+# This file contains the default images and tags used in the docker-based
+# Fabric fixtures. The images and tags can be overridden using environment
+# variables. See docker compose documentation.
+
+
+# Agent configurations
+AGENT_REST_IMAGE=docker.pkg.github.com/trustbloc/agent-sdk/agent-sdk-rest
+AGENT_REST_IMAGE_TAG=latest
+
+# HTTP Resolver Configurations
+HTTP_DID_RESOLVER=sidetree@http://agent.sdk.sidetree.mock:48326/sidetree/0.0.1/identifiers
+
+# Transport Schemes
+HTTP_SCHEME=http
+WS_SCHEME=ws
+
+# Aries Framework Configurations
+TRANSPORT_RETURN_OPTION_ALL=all
+
+# Alice agent configurations
+ALICE_HOST=0.0.0.0
+ALICE_INBOUND_PORT=8081
+ALICE_API_PORT=8082
+
+# Bob agent configurations
+BOB_HOST=0.0.0.0
+BOB_INBOUND_PORT=9081
+BOB_API_PORT=9082
+
+# Carl agent configurations
+CARL_HOST=0.0.0.0
+CARL_API_PORT=10081
+
+# Carl router configurations
+CARL_ROUTER_HOST=0.0.0.0
+CARL_ROUTER_HTTP_INBOUND_PORT=10091
+CARL_ROUTER_WS_INBOUND_PORT=10092
+CARL_ROUTER_API_PORT=10093

deployments/agent-rest/docker-compose.yml

@@ -0,0 +1,108 @@
+#
+# Copyright IBM Corp, SecureKey Technologies Inc. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+version: '2'
+
+services:
+
+  alice.agent.sdk.example.com:
+    container_name: alice.agent.sdk.example.com
+    image: ${AGENT_REST_IMAGE}:${AGENT_REST_IMAGE_TAG}
+    environment:
+      - ARIESD_API_HOST=${ALICE_HOST}:${ALICE_API_PORT}
+      - ARIESD_INBOUND_HOST=${HTTP_SCHEME}@${ALICE_HOST}:${ALICE_INBOUND_PORT}
+      - ARIESD_INBOUND_HOST_EXTERNAL=${HTTP_SCHEME}@https://alice.agent.sdk.example.com:${ALICE_INBOUND_PORT}
+      - ARIESD_DEFAULT_LABEL=alice-agent
+      - ARIESD_DATABASE_TYPE=leveldb
+      - ARIESD_DATABASE_PREFIX=alice
+      - ARIESD_DATABASE_TIMEOUT=60
+      - ARIESD_HTTP_RESOLVER=${HTTP_DID_RESOLVER}
+      - TLS_CERT_FILE=/etc/tls/ec-pubCert.pem
+      - TLS_KEY_FILE=/etc/tls/ec-key.pem
+    volumes:
+      - ../keys/tls:/etc/tls
+    ports:
+      - ${ALICE_INBOUND_PORT}:${ALICE_INBOUND_PORT}
+      - ${ALICE_API_PORT}:${ALICE_API_PORT}
+    entrypoint: ""
+    command:  /bin/sh -c "cp /etc/tls/* /usr/local/share/ca-certificates/;update-ca-certificates; agent-rest start"
+    networks:
+      - agent_sdk_net
+
+  bob.agent.sdk.example.com:
+    container_name: bob.agent.sdk.example.com
+    image: ${AGENT_REST_IMAGE}:${AGENT_REST_IMAGE_TAG}
+    environment:
+      - ARIESD_API_HOST=${BOB_HOST}:${BOB_API_PORT}
+      - ARIESD_INBOUND_HOST=${HTTP_SCHEME}@${BOB_HOST}:${BOB_INBOUND_PORT}
+      - ARIESD_INBOUND_HOST_EXTERNAL=${HTTP_SCHEME}@https://bob.agent.sdk.example.com:${BOB_INBOUND_PORT}
+      - ARIESD_DATABASE_TYPE=leveldb
+      - ARIESD_DATABASE_PREFIX=bob
+      - ARIESD_DATABASE_TIMEOUT=60
+      - ARIESD_DEFAULT_LABEL=bob-agent
+      - ARIESD_HTTP_RESOLVER=${HTTP_DID_RESOLVER}
+      - TLS_CERT_FILE=/etc/tls/ec-pubCert.pem
+      - TLS_KEY_FILE=/etc/tls/ec-key.pem
+    volumes:
+      - ../keys/tls:/etc/tls
+    ports:
+      - ${BOB_INBOUND_PORT}:${BOB_INBOUND_PORT}
+      - ${BOB_API_PORT}:${BOB_API_PORT}
+    entrypoint: ""
+    command:  /bin/sh -c "cp /etc/tls/* /usr/local/share/ca-certificates/;update-ca-certificates; agent-rest start"
+    networks:
+      - agent_sdk_net
+
+  carl.agent.sdk.example.com:
+    container_name: carl.agent.sdk.example.com
+    image: ${AGENT_REST_IMAGE}:${AGENT_REST_IMAGE_TAG}
+    environment:
+      - ARIESD_API_HOST=${CARL_HOST}:${CARL_API_PORT}
+      - ARIESD_DEFAULT_LABEL=carl-agent
+      - ARIESD_DATABASE_TYPE=leveldb
+      - ARIESD_DATABASE_PREFIX=carl
+      - ARIESD_DATABASE_TIMEOUT=60
+      - ARIESD_OUTBOUND_TRANSPORT=${HTTP_SCHEME},${WS_SCHEME}
+      - ARIESD_TRANSPORT_RETURN_ROUTE=${TRANSPORT_RETURN_OPTION_ALL}
+      - TLS_CERT_FILE=/etc/tls/ec-pubCert.pem
+      - TLS_KEY_FILE=/etc/tls/ec-key.pem
+    volumes:
+      - ../keys/tls:/etc/tls
+    ports:
+      - ${CARL_API_PORT}:${CARL_API_PORT}
+    entrypoint: ""
+    command:  /bin/sh -c "cp /etc/tls/* /usr/local/share/ca-certificates/;update-ca-certificates; agent-rest start"
+    networks:
+      - agent_sdk_net
+
+  carl.router.agent.sdk.example.com:
+    container_name: carl.router.agent.sdk.example.com
+    image: ${AGENT_REST_IMAGE}:${AGENT_REST_IMAGE_TAG}
+    environment:
+      - ARIESD_API_HOST=${CARL_ROUTER_HOST}:${CARL_ROUTER_API_PORT}
+      - ARIESD_INBOUND_HOST=${HTTP_SCHEME}@${CARL_ROUTER_HOST}:${CARL_ROUTER_HTTP_INBOUND_PORT},${WS_SCHEME}@${CARL_ROUTER_HOST}:${CARL_ROUTER_WS_INBOUND_PORT}
+      - ARIESD_INBOUND_HOST_EXTERNAL=${HTTP_SCHEME}@https://carl.router.agent.sdk.example.com:${CARL_ROUTER_HTTP_INBOUND_PORT},${WS_SCHEME}@wss://carl.router.agent.sdk.example.com:${CARL_ROUTER_WS_INBOUND_PORT}
+      - ARIESD_DATABASE_TYPE=leveldb
+      - ARIESD_DATABASE_PREFIX=carl_router
+      - ARIESD_DATABASE_TIMEOUT=60
+      - ARIESD_DEFAULT_LABEL=carl-router-agent
+      - ARIESD_OUTBOUND_TRANSPORT=${HTTP_SCHEME},${WS_SCHEME}
+      - ARIESD_HTTP_RESOLVER=${HTTP_DID_RESOLVER}
+      - TLS_CERT_FILE=/etc/tls/ec-pubCert.pem
+      - TLS_KEY_FILE=/etc/tls/ec-key.pem
+    volumes:
+      - ../keys/tls:/etc/tls
+    ports:
+      - ${CARL_ROUTER_HTTP_INBOUND_PORT}:${CARL_ROUTER_HTTP_INBOUND_PORT}
+      - ${CARL_ROUTER_WS_INBOUND_PORT}:${CARL_ROUTER_WS_INBOUND_PORT}
+      - ${CARL_ROUTER_API_PORT}:${CARL_ROUTER_API_PORT}
+    entrypoint: ""
+    command:  /bin/sh -c "cp /etc/tls/* /usr/local/share/ca-certificates/;update-ca-certificates; agent-rest start"
+    networks:
+      - agent_sdk_net
+
+networks:
+  agent_sdk_net:
+    driver: bridge

deployments/demo/openapi/.env

@@ -0,0 +1,16 @@
+#
+# Copyright SecureKey Technologies Inc. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+# This file contains the default images and tags used in the docker-based
+# Fabric fixtures. The images and tags can be overridden using environment
+# variables. See docker compose documentation.
+
+
+# Demo Agent API hosts
+ALICE_API_HOST=localhost:8082
+BOB_API_HOST=localhost:9082
+CARL_API_HOST=localhost:10081
+CARL_ROUTER_API_HOST=localhost:10093

deployments/demo/openapi/docker-compose.yml

@@ -0,0 +1,64 @@
+#
+# Copyright IBM Corp, SecureKey Technologies Inc. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+version: '2'
+
+services:
+
+  alice.sdk.openapi.demo.com:
+    container_name: alice.sdk.openapi.demo.com
+    image: swaggerapi/swagger-ui
+    environment:
+      - SWAGGER_JSON=/specs/openapi-${ALICE_API_HOST}.yml
+      - BASE_URL=/openapi
+    ports:
+      - 8089:8080
+    volumes:
+      - ./specs:/specs
+    networks:
+      - agent-sdk-rest-net
+
+  bob.sdk.openapi.demo.com:
+    container_name: bob.sdk.openapi.demo.com
+    image: swaggerapi/swagger-ui
+    environment:
+      - SWAGGER_JSON=/specs/openapi-${BOB_API_HOST}.yml
+      - BASE_URL=/openapi
+    ports:
+      - 9089:8080
+    volumes:
+      - ./specs:/specs
+    networks:
+      - agent-sdk-rest-net
+
+  carl.sdk.openapi.demo.com:
+    container_name: carl.sdk.openapi.demo.com
+    image: swaggerapi/swagger-ui
+    environment:
+      - SWAGGER_JSON=/specs/openapi-${CARL_API_HOST}.yml
+      - BASE_URL=/openapi
+    ports:
+      - 10089:8080
+    volumes:
+      - ./specs:/specs
+    networks:
+      - agent-sdk-rest-net
+
+  carl.router.sdk.openapi.demo.com:
+    container_name: carl.router.sdk.openapi.demo.com
+    image: swaggerapi/swagger-ui
+    environment:
+      - SWAGGER_JSON=/specs/openapi-${CARL_ROUTER_API_HOST}.yml
+      - BASE_URL=/openapi
+    ports:
+      - 10099:8080
+    volumes:
+      - ./specs:/specs
+    networks:
+      - agent-sdk-rest-net
+
+networks:
+  agent-sdk-rest-net:
+    external: true

deployments/sidetree-mock/.env

@@ -0,0 +1,15 @@
+#
+# Copyright SecureKey Technologies Inc. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+# This file contains the default images and tags used in the docker
+# The images and tags can be overridden using environment
+# variables. See docker compose documentation.
+
+COMPOSE_DIR=.
+
+# sidetree mock
+SIDETREE_MOCK_FIXTURE_IMAGE=docker.pkg.github.com/trustbloc-cicd/snapshot/sidetree-mock
+SIDETREE_MOCK_FIXTURE_IMAGE_TAG=0.1.5-snapshot-7375c22