@@ -1,52 +1,96 @@
3The package is the client library for the [mock server](https://www.mock-server.com/). The source code is
3The package is the client library for the [mock server](https://www.mock-server.com/). The source code is
4generated by the [openapi3-code-generator](https://hackage.haskell.org/package/openapi3-code-generator), specifically its patched version.
4generated by the [openapi3-code-generator](https://hackage.haskell.org/package/openapi3-code-generator), specifically its patched version.
6−## How to regenerate
6+## Usage
9−cd codegen && ./regen.sh
9+module Main
12−It requires the `nix` to be installed in your system because it uses the
11+import MockServer as Mock
13−`openapi3-code-generator` built by the `nix`.
12+import Network.HTTP.Client
15−After regeneration you will see some `.hs` files changed. This is because some
14+conf :: Mock.Configuration
16−parts of the libary are modified by hand to make the more usable.
15+conf = Configuration
16+ { configBaseURL = "http://localhost"
17+ , configSecurityScheme = id
18+ , configIncludeUserAgent = False
19+ , configApplicationName = "ping-app" }
21+expectation :: Mock.Expectations
22+expectation = Mock.ExpectationsExpectation $ Mock.mkExpectation
23+ { expectationHttpRequest = Just request
24+ , expectationHttpResponse = Just response }
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 }
33+-- | Puts the expectation which will response with "pong" body to the "POST /ping" request
36+ void $ Mock.runWithConfiguration conf $ Mock.put_mockserver_expectation expectation
20### The `codegen` dir
43### The `codegen` dir
22* `regen.sh` is the simple script to regenerate the whole package.
45* `regen.sh` is the simple script to regenerate the whole package.
23−* `shell.nix` a shell in which the `regen.sh` calls the `openapi3-code-generator` to regenerate the
46+* `shell.nix` a shell in which the `regen.sh` calls the `openapi3-code-generator` to regenerate the code
24−* `mock-server-openapi-5.13.x-swagger.yaml` not the original file as you might
47+* `mock-server-openapi.yaml` not the [original specification](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi) of the `mock-server` as you might
25− think. The thing is that the `openapi3-code-generator` does not support all
48+ think. The thing is that the `openapi3-code-generator` does not support all the features of the
26− the features of the OpenAPI3 standard correctly, so it is
49+ OpenAPI3 standard correctly, so it is hand-postprocessed. It was originally downloaded from
27− hand-postprocessed. It was originally downloaded from [here](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.13.x) and fixed.
50+ [here](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.13.x) and fixed.
28−* `src` contails the generted code, but not exactly. Some of the parts of the
51+
29− generted code was not very pleasant, so it was fixed too.
52+### Other
54+* `src` and `mock-server-client.cabal` contain the generted code, but not exactly. Some of the parts
55+ of the generted code was not very pleasant, so it was fixed too.
31−### What will happen if you just call the `regen.sh`?
57+## What will happen if you just call the `regen.sh`?
33It will build the `openapi3-code-generator` in `nix` and regenerate the whole
59It will build the `openapi3-code-generator` in `nix` and regenerate the whole
34Haskell source code. You will see that the code was changed, because as
60Haskell source code. You will see that the code was changed, because as
35mentioned earlier the original code was slightly modified, so watch your commits.
61mentioned earlier the original code was slightly modified, so watch your commits.
37−## How the to update the package to the new version of the `mock-server`?
63+## How to update the package to the new version of the `mock-server` spec?
39−* Commit all changes in git
65+* Commit or discard all changes
40−* Run the `regen.sh` and regenerate the whole package
66+* `git checkout update-openapi-spec`
41−* Run `git diff -p > src.patch` and save the manual changes made to the source code
67+* Replace the `codegen/mock-server-openapi.yaml` with a newer version
42−* Download the [original spec](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.13.x) in place of our patched spec file
68+* `git commit -m "updated mock-server-openapi.yaml to version $NEWVERSION"`
43−* Run the `git diff -- codegen/mock-server-openapi-5.13.x-swagger.yaml -p > spec.patch`
69+* `git checkout -b "update-$NEWVERSION" master`
44−* Download the [new spec](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi) and put it in place of the old one
70+* `git merge update-openapi-spec`
45−* Try to `git apply spec.patch` to the newer version of the spec to apply manual
71+* Resolve conflicts if any
46− changes to the new spec. If somethig goes wrong use AI to fix it for you, heh.
72+* `./codegen/regen.sh`
47−* Fix the `regen.sh` and rename the `mock-server-openapi-5.13.x-swagger.yaml` to
73+* `git symbolic-ref HEAD refs/heads/update-generated-code && git reset`
48− the newer version.
74+ switching to the branch `update-generated-code` without checking out the working-tree
49−* `git commit -m 'dangerous action'`
75+* `git commit -m "update the generted code for version $NEWVERSION"`
50−* Run the `regen.sh` so you will hopefuly have a new version of the client code
76+* `git checkout "update-$NEWVERSION"`
51− generated.
77+* `git merge update-generated-code`
52−* `git apply src.patch` to apply manual patches to the new version.
78+* Resolve conflicts if any
79+* `git push origin "update-$NEWVERSION"`
80+* Create PR, wait for CI, review, merge into the master
82+The algorithm is kind of weird, but for a reason.
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`.
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.
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`