From 4e38273b689852ffad0c091a2067a682d438e5f4 Mon Sep 17 00:00:00 2001 From: jbion Date: Mon, 10 Apr 2017 17:56:08 +0200 Subject: Add documentation regarding the addition of the live API doc --- README.md | 5 +++- doc/decisions_history.md | 62 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 49 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4e5fb31e..2809f05d 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ Missing steps: - End of game event - Access scoring +A [live API documentation using JsonDoc](https://seven-wonders-online.herokuapp.com/jsondoc-ui.html?url=https://seven-wonders-online.herokuapp.com/doc) +is available. It is in construction as well because I'm adding wesocket support to the existing REST-API support. + ### Client The client is just at the start of the development. It handles: @@ -40,4 +43,4 @@ Missing steps: ## Disclaimer -We do not own the rights on the 7 Wonders game concept and rules, nor on the assets used here. \ No newline at end of file +We do not own the rights on the 7 Wonders game concept and rules, nor on the assets used here. diff --git a/doc/decisions_history.md b/doc/decisions_history.md index 592fb1be..90656e4c 100644 --- a/doc/decisions_history.md +++ b/doc/decisions_history.md @@ -1,31 +1,57 @@ # Technical decisions and issues log +## 2017-04-06 Live API documentation +:key: : Backend, API, Documentation + +As frontend development was starting, we felt the need for a better API doc than a plain shared Google Sheet. +The best doc is an up-to-date doc that stays so. The easiest way I found to keep it up-to-date is to generate it. + +Now multiple tools were available, but none really for websocket APIs documentation. Most of the tools out there are +specialized in REST APIs. A very popular one is [Swagger](http://swagger.io/), but it +[can't be used](https://github.com/swagger-api/swagger-socket/issues/47) +[yet for Websocket](https://github.com/OAI/OpenAPI-Specification/issues/523) communications. + +My attention then went to [JsonDoc](http://jsondoc.org/), which looked promising but with the same drawbacks: no +support for publich/subscribe mechanisms like websockets. Contributing to the project seems easier than contributing +to Swagger, and I already could tweak a little bit the source code of JsonDoc to support `@MessageMapping` methods. + +That being said, Fabio Mafioletti does not seem to have a lot of time available for collaboration in implementing +this support, so I might have to release from my own fork of the project, or create a new project based on JsonDoc. + ## 2017-01-20 Frontend architecture refactoring :key: : Frontend -I based the frontend architecture on [mxstbr's](https://twitter.com/mxstbr) [react-boilerplate](https://github.com/mxstbr/react-boilerplate) (thanks Max!). The recommended structure for his boilerplate is to group files by features. As such, in a feature folder, you would find reducers, actions types and creators, selectors, sagas as well as containers. +I based the frontend architecture on [mxstbr's](https://twitter.com/mxstbr) +[react-boilerplate](https://github.com/mxstbr/react-boilerplate) (thanks Max!). The recommended structure for his +boilerplate is to group files by features. As such, in a feature folder, you would find reducers, actions types and +creators, selectors, sagas as well as containers. -At first, this choice seemed suitable for our project but with time, I found out that it was causing us headaches because of the amount of shared data and logic we have between containers and pages. This is when I remembered [Matteo's](https://twitter.com/mazzarolomatteo) blog post on [a maintainable project structure](https://hackernoon.com/my-journey-toward-a-maintainable-project-structure-for-react-redux-b05dfd999b5#.o9pn60cv9) from last october. I highly recommend reading. +At first, this choice seemed suitable for our project but with time, I found out that it was causing us headaches +because of the amount of shared data and logic we have between containers and pages. This is when I remembered +[Matteo's](https://twitter.com/mazzarolomatteo) blog post on +[a maintainable project structure](https://hackernoon.com/my-journey-toward-a-maintainable-project-structure-for-react-redux-b05dfd999b5#.o9pn60cv9) from last october. I highly recommend reading. -I refactored our code to use the `Ducks` principle (the word comes from re*DUX*) and I can already see the ease to import all redux specific files. -I will update this section with more info after using it more extensively. +I refactored our code to use the `Ducks` principle (the word comes from re*DUX*) and I can already see the ease to +import all redux specific files. I will update this section with more info after using it more extensively. ## 2017-01-20 Unified build Spring Boot + React :key: : Frontend, Backend +I wanted to make use of the local `package.json` scripts to be consistent with the frontend development workflow. +That way, the global build would not bring any surprise compared to the standalone frontend build. Some other nice +plugins allowed for bundling, minification etc. directly from Gradle, but that's not exactly what I wanted for the +reason I just described. -Using the initial `src/main/js` was troublesome, because it didn't really follow any standard, and we would need a local -`build.gradle` to handle the frontend in order to be clean. It eventually made more sense to separate the react app -sources in a subproject, following the example of [Geowarin Boot React](https://github.com/geowarin/boot-react/). - -I wanted to make use of the local `package.json` scripts to be consistent with the development workflow and take -advantage of Create React App's genericity. Some other nice plugins allowed for bundling, minification etc. directly -from Gradle, but that's not exactly what I wanted. +In order to take advantage of Create React App's genericity, I could not temper with the webpack config in order to +customize the source path to `src/main/js`, like in the example of +[Spring React Boilerplate](https://github.com/pugnascotia/spring-react-boilerplate). It eventually made more sense to + separate the react app sources in a subproject, following the example of + [Geowarin Boot React](https://github.com/geowarin/boot-react/). Using the [Gradle Node Plugin](https://github.com/srs/gradle-node-plugin) and its Yarn tasks allowed for an easy setup of the react frontend build. It already solved most of the frontend build problems: download node/npm/yarn, install dependencies, bundle the JS using the frontend tools... We just had to include the result of the frontend build into the -`static` folder of the backend jar. +`static` folder of the backend jar, by customizing the backend's `build.gradle`. #### Heroku issues @@ -44,8 +70,8 @@ to add a Procfile to manually specify the `backend` subproject in the process co ## 2016-12-08 React frontend :key: : Frontend -We decided to put the react stuff into `src/main/js` as it seems to follow the conventions. As `src/main/java` contains -the Java sources, why not put the JavaScript sources in `src/main/js`? +We decided to put the react stuff into `src/main/js` as it matches maven/gradle project structure conventions. As +`src/main/java` contains the Java sources, why not put the JavaScript sources in `src/main/js`? Technical decisions: @@ -66,11 +92,13 @@ independently and both the frontend dev server and the spring boot server can ru Technical decisions: - [Websockets](https://en.wikipedia.org/wiki/WebSocket): as we want server pushes to reach all clients when a player -plays a card, we chose Websockets as main transport. +plays a card, we chose Websockets as main transport. HTTP/2 didn't seem to have proper browser support at the moment, + and long polling is not a very clean solution to this problem. - [Spring Boot Websocket](https://spring.io/guides/gs/messaging-stomp-websocket/): because of my personal preference for -and ease with the Java language, and because it is really quick to setup. It has the advantage to run without a -container, with a simple `main()` method which also pretty cool. +(and ease with) the Java language, and because it is really quick to setup, Spring Boot was our choice as backend. It +has the advantage to run without a container, with a simple `main()` method which also pretty cool. This gave us the +quickest start as far as the backend was concerned. - [STOMP](https://en.wikipedia.org/wiki/Streaming_Text_Oriented_Messaging_Protocol): coming with Spring official support, it was quite natural to use STOMP over Websockets as a subprotocol. It allows for an easier management of the -- cgit