@@ -1,19 +1,42 @@
1−## About
1+# About
22
33The package is the client library for the [mock server](https://www.mock-server.com/). The source code is
44generated by the [openapi3-code-generator](https://hackage.haskell.org/package/openapi3-code-generator), specifically its patched version.
55
6−## How to regenerate code from the spec
6+## Usage
77
8−```
9−cd codegen && ./regen.sh
10−```
8+``` haskell
9+module Main
10+
11+import MockServer as Mock
12+import Network.HTTP.Client
1113
12−It requires the `nix` to be installed in your system because it uses the
13−`openapi3-code-generator` built by the `nix`.
14+conf :: Mock.Configuration
15+conf = Configuration
16+ { configBaseURL = "http://localhost"
17+ , configSecurityScheme = id
18+ , configIncludeUserAgent = False
19+ , configApplicationName = "ping-app" }
20+
21+expectation :: Mock.Expectations
22+expectation = Mock.ExpectationsExpectation $ Mock.mkExpectation
23+ { expectationHttpRequest = Just request
24+ , expectationHttpResponse = Just response }
25+ where
26+ request = Mock.mkHttpRequest
27+ { httpRequestMethod = Just $ StringOrJsonSchemaText "POST"
28+ , httpRequestPath = Just $ StringOrJsonSchemaText "/ping" }
29+ response = Mock.mkHttpResponse
30+ { httpResponseBody = Just $ BodyWithContentTypeRawStringResponseBody "pong"
31+ , httpResponseStatusCode = Just 200 }
32+
33+-- | Puts the expectation which will response with "pong" body to the "POST /ping" request
34+main :: IO ()
35+main = do
36+ void $ Mock.runWithConfiguration conf $ Mock.put_mockserver_expectation expectation
37+```
1438
15−After regeneration you will see some `.hs` files changed. This is because some
16−parts of the libary are modified by hand to make the more usable.
39+# Maintainance
1740
1841## Files
1942
@@ -25,10 +48,13 @@ parts of the libary are modified by hand to make the more usable.
2548 think. The thing is that the `openapi3-code-generator` does not support all
2649 the features of the OpenAPI3 standard correctly, so it is
2750 hand-postprocessed. It was originally downloaded from [here](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.13.x) and fixed.
51+
52+### Other
53+
2854* `src` contails the generted code, but not exactly. Some of the parts of the
2955 generted code was not very pleasant, so it was fixed too.
3056
31−### What will happen if you just call the `regen.sh`?
57+## What will happen if you just call the `regen.sh`?
3258
3359It will build the `openapi3-code-generator` in `nix` and regenerate the whole
3460Haskell source code. You will see that the code was changed, because as
@@ -52,3 +78,19 @@ mentioned earlier the original code was slightly modified, so watch your commits
5278* Resolve conflicts if any
5379* `git push origin "update-$NEWVERSION"`
5480* Create PR, wait for CI, review, merge into the master
81+
82+The algorithm is kind of weird, but for a reason.
83+
84+The branch `update-openapi-spec` is the branch tracking only original
85+`codegen/mock-server-openapi.yaml` changes, meaning changes made by authors of the
86+`mock-server`. So, when you merge changes of this branch into the master you literally merge the
87+changes made by authors of the `mock-server` with our manual changes made to please the
88+`openapi3-code-generator`.
89+
90+The bratch `update-generated-code` is for tracking "changes" made by the code generator when it is
91+feed by the new OpenAPI spec file. So, when you merge this branch into the master you literally
92+merge the "code regeneration patch" with changes made by hand.
93+
94+The `master` branch is for manual changes only. The changes made to keep things working and the
95+package usable. You can always see the manual changes just by `git diff update-generated-code
96+master` or `git diff update-openapi-spec master`