Close #14, add swagger to API

Api/api-app/pom.xml

@@ -23,10 +23,6 @@
     </properties>
 
     <dependencies>
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter</artifactId>
-        </dependency>
         <dependency>
             <groupId>org.jetbrains.kotlin</groupId>
             <artifactId>kotlin-reflect</artifactId>
@@ -68,6 +64,11 @@
             <artifactId>api-persister-postgres</artifactId>
             <version>${api.version}</version>
         </dependency>
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-boot-starter</artifactId>
+            <version>3.0.0</version>
+        </dependency>
 
         <dependency>
             <groupId>org.springframework.boot</groupId>

Api/api-app/src/main/kotlin/co/nilin/opex/app/ApiApp.kt

@@ -2,12 +2,102 @@ package co.nilin.opex.app
 
 import org.springframework.boot.autoconfigure.SpringBootApplication
 import org.springframework.boot.runApplication
+import org.springframework.context.annotation.Bean
 import org.springframework.context.annotation.ComponentScan
+import org.springframework.security.core.annotation.AuthenticationPrincipal
+import springfox.documentation.builders.*
+import springfox.documentation.builders.PathSelectors.regex
+import springfox.documentation.service.*
+import springfox.documentation.spi.DocumentationType
+import springfox.documentation.spi.service.contexts.SecurityContext
+import springfox.documentation.spring.web.plugins.Docket
+import springfox.documentation.swagger.web.SecurityConfiguration
+import springfox.documentation.swagger.web.SecurityConfigurationBuilder
+import springfox.documentation.swagger2.annotations.EnableSwagger2
+import java.security.Principal
+import java.util.Collections.singletonList
+
 
 @SpringBootApplication
 @ComponentScan("co.nilin.opex")
-class AccountantApp
+@EnableSwagger2
+class ApiApp {
+    @Bean
+    fun opexApi(): Docket? {
+        return Docket(DocumentationType.SWAGGER_2)
+            .groupName("opex-api")
+            .apiInfo(apiInfo())
+            .select()
+            .paths(regex("^/api/v3.*"))
+            .build()
+            .globalRequestParameters(
+                singletonList(
+                    RequestParameterBuilder()
+                        .name("content-type")
+                        .description("content-type")
+                        .`in`(ParameterType.HEADER)
+                        .required(true)
+                        .build()
+                )
+            )
+            .ignoredParameterTypes(AuthenticationPrincipal::class.java, Principal::class.java)
+            .useDefaultResponseMessages(false)
+            .securitySchemes(singletonList(oauth()))
+            .securityContexts(singletonList(securityContext()))
+    }
+
+    private fun apiInfo(): ApiInfo? {
+        return ApiInfoBuilder()
+            .title("OPEX API")
+            .description("Backend for opex exchange.")
+            .license("MIT License")
+            .licenseUrl("https://github.com/opexdev/Back-end/blob/feature/1-MVP/LICENSE")
+            .version("0.1")
+            .build()
+    }
+
+    @Bean
+    fun oauth(): SecurityScheme? {
+        return OAuthBuilder()
+            .name("opex")
+            .grantTypes(grantTypes())
+            .scopes(scopes())
+            .build()
+    }
+
+    fun scopes(): List<AuthorizationScope?>? {
+        return emptyList()
+    }
+
+    fun grantTypes(): List<GrantType?>? {
+        val tokenUrl = "http://localhost:8083/auth/realms/mixchange/protocol/openid-connect/token"
+        val grantType = ResourceOwnerPasswordCredentialsGrant(tokenUrl)
+        return singletonList(grantType)
+    }
+
+    @Bean
+    fun securityContext(): SecurityContext? {
+        val securityReference = SecurityReference.builder()
+            .reference("opex")
+            .scopes(emptyArray())
+            .build()
+        return SecurityContext.builder()
+            .securityReferences(singletonList(securityReference))
+            .operationSelector { true }
+            .build()
+    }
+
+    @Bean
+    fun securityInfo(): SecurityConfiguration? {
+        return SecurityConfigurationBuilder.builder()
+            .clientId("admin-cli")
+            .realm("mixchange")
+            .appName("opex")
+            .scopeSeparator(",")
+            .build()
+    }
+}
 
 fun main(args: Array<String>) {
-    runApplication<AccountantApp>(*args)
-}
+    runApplication<ApiApp>(*args)
+}

Api/api-ports/api-binance-rest/pom.xml

@@ -102,6 +102,11 @@
             <artifactId>reactor-test</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-annotations</artifactId>
+            <version>1.5.20</version>
+        </dependency>
     </dependencies>
 
     <build>

Api/api-ports/api-binance-rest/src/main/kotlin/co/nilin/opex/port/api/binance/config/SecurityConfig.kt

@@ -23,6 +23,9 @@ class SecurityConfig {
             .authorizeExchange()
             .pathMatchers("/hello").permitAll()
             .pathMatchers("/actuator/**").permitAll()
+            .pathMatchers("/swagger-ui/**").permitAll()
+            .pathMatchers("/swagger-resources/**").permitAll()
+            .pathMatchers("/v2/api-docs").permitAll()
             .pathMatchers("/**").hasAuthority("SCOPE_trust")
             .anyExchange().authenticated()
             .and()

Api/api-ports/api-binance-rest/src/main/kotlin/co/nilin/opex/port/api/binance/controller/AccountController.kt

@@ -12,15 +12,13 @@ import co.nilin.opex.port.api.binance.util.asMatchingOrderType
 import co.nilin.opex.port.api.binance.util.asOrderDirection
 import co.nilin.opex.api.core.inout.*
 import com.fasterxml.jackson.annotation.JsonInclude
+import io.swagger.annotations.*
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.map
 import org.slf4j.LoggerFactory
 import org.springframework.http.MediaType
 import org.springframework.security.core.annotation.AuthenticationPrincipal
-import org.springframework.web.bind.annotation.GetMapping
-import org.springframework.web.bind.annotation.PostMapping
-import org.springframework.web.bind.annotation.RequestParam
-import org.springframework.web.bind.annotation.RestController
+import org.springframework.web.bind.annotation.*
 import java.math.BigDecimal
 import java.security.Principal
 import java.util.*
@@ -108,6 +106,16 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "{ \"symbol\": \"btc_usdt\", \"orderId\": -1, \"orderListId\": -1, \"transactTime\": \"2021-08-03T11:09:23.190+00:00\" }",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun createNewOrder(
         @RequestParam(name = "symbol")
         symbol: String,
@@ -123,16 +131,24 @@ class AccountController(
         quoteOrderQty: BigDecimal?,
         @RequestParam(name = "price", required = false)
         price: BigDecimal?,
+        @ApiParam(
+            value = "A unique id among open orders. Automatically generated if not sent.\n" +
+                    "Orders with the same newClientOrderID can be accepted only when the previous one is filled, otherwise the order will be rejected."
+        )
         @RequestParam(name = "newClientOrderId", required = false)
         newClientOrderId: String?,    /* A unique id among open orders. Automatically generated if not sent.
     Orders with the same newClientOrderID can be accepted only when the previous one is filled, otherwise the order will be rejected.
     */
+        @ApiParam(value = "Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.")
         @RequestParam(name = "stopPrice", required = false)
         stopPrice: BigDecimal?, //Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
         @RequestParam(name = "icebergQty", required = false)
+        @ApiParam(value = "Used with LIMIT, STOP_LOSS_LIMIT, and TAKE_PROFIT_LIMIT to create an iceberg order.")
         icebergQty: BigDecimal?, //Used with LIMIT, STOP_LOSS_LIMIT, and TAKE_PROFIT_LIMIT to create an iceberg order.
         @RequestParam(name = "newOrderRespType", required = false)
+        @ApiParam(value = "Set the response JSON. ACK, RESULT, or FULL; MARKET and LIMIT order types default to FULL, all other orders default to ACK.")
         newOrderRespType: OrderResponseType?,  //Set the response JSON. ACK, RESULT, or FULL; MARKET and LIMIT order types default to FULL, all other orders default to ACK.
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")
@@ -179,6 +195,16 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "{ \"symbol\": \"btc_usdt\", \"orderId\": 12, \"orderListId\": -1, \"clientOrderId\": \"\", \"price\": 1, \"origQty\": 10, \"executedQty\": 0, \"cummulativeQuoteQty\": 0, \"status\": \"NEW\", \"timeInForce\": \"GTC\", \"type\": \"LIMIT\", \"side\": \"SELL\", \"time\": \"2021-08-04T12:10:13.488+00:00\", \"updateTime\": \"2021-08-04T12:10:13.488+00:00\", \"isWorking\": true, \"origQuoteOrderQty\": 10 }",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun queryOrder(
         principal: Principal,
         @RequestParam(name = "symbol")
@@ -187,6 +213,7 @@ class AccountController(
         orderId: Long?,
         @RequestParam(name = "origClientOrderId", required = false)
         origClientOrderId: String?,
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")
@@ -230,10 +257,21 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "[ { \"symbol\": \"btc_usdt\", \"orderId\": 12, \"orderListId\": -1, \"clientOrderId\": \"\", \"price\": 1, \"origQty\": 10, \"executedQty\": 0, \"cummulativeQuoteQty\": 0, \"status\": \"NEW\", \"timeInForce\": \"GTC\", \"type\": \"LIMIT\", \"side\": \"SELL\", \"time\": \"2021-08-04T12:10:13.488+00:00\", \"updateTime\": \"2021-08-04T12:10:13.488+00:00\", \"isWorking\": true, \"origQuoteOrderQty\": 10 } ]",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun fetchOpenOrders(
         principal: Principal,
         @RequestParam(name = "symbol", required = false)
         symbol: String?,
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")
@@ -274,6 +312,16 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "{ }",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun fetchAllOrders(
         principal: Principal,
         @RequestParam(name = "symbol", required = false)
@@ -282,8 +330,10 @@ class AccountController(
         startTime: Date?,
         @RequestParam(name = "endTime", required = false)
         endTime: Date?,
+        @ApiParam(value = "Default 500; max 1000.")
         @RequestParam(name = "limit", required = false)
         limit: Int? = 500, //Default 500; max 1000.
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")
@@ -325,6 +375,16 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "{ }",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun fetchAllTrades(
         principal: Principal,
         @RequestParam(name = "symbol")
@@ -333,10 +393,13 @@ class AccountController(
         startTime: Date?,
         @RequestParam(name = "endTime", required = false)
         endTime: Date?,
+        @ApiParam(value = "TradeId to fetch from. Default gets most recent trades.")
         @RequestParam(name = "fromId", required = false)
         fromId: Long?,//TradeId to fetch from. Default gets most recent trades.
+        @ApiParam(value = "Default 500; max 1000.")
         @RequestParam(name = "limit", required = false)
         limit: Int? = 500, //Default 500; max 1000.
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")
@@ -358,9 +421,20 @@ class AccountController(
         consumes = [MediaType.APPLICATION_FORM_URLENCODED_VALUE],
         produces = [MediaType.APPLICATION_JSON_VALUE]
     )
+    @ApiResponse(
+        message = "OK",
+        code = 200,
+        examples = Example(
+            ExampleProperty(
+                value = "{ \"makerCommission\": 0, \"takerCommission\": 0, \"buyerCommission\": 0, \"sellerCommission\": 0, \"canTrade\": true, \"canWithdraw\": true, \"canDeposit\": true, \"updateTime\": 1628420513843, \"accountType\": \"SPOT\", \"balances\": [ { \"asset\": \"usdt\", \"free\": 1000, \"locked\": 0 } ], \"permissions\": [ \"SPOT\" ] }",
+                mediaType = "application/json"
+            )
+        )
+    )
     suspend fun accountInfo(
         @AuthenticationPrincipal
         auth: CustomAuthToken,
+        @ApiParam(value = "The value cannot be greater than 60000")
         @RequestParam(name = "recvWindow", required = false)
         recvWindow: Long?, //The value cannot be greater than 60000
         @RequestParam(name = "timestamp")

MatchingGateway/gateway-app/pom.xml

@@ -84,6 +84,11 @@
             <artifactId>bcprov-jdk15on</artifactId>
             <version>1.60</version>
         </dependency>
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-boot-starter</artifactId>
+            <version>3.0.0</version>
+        </dependency>
     </dependencies>
     <dependencyManagement>
         <dependencies>