|
Swagger was chosen due to:
- Easy generation of server and client boilerplate code in many languages.
(in Weles project only golang is used but the swagger.yml file can be used
to generate Weles server/client boilerplate in any language)
- Clear, automatically generated documentation
- Promising standard that this tool is based on:
https://github.com/OAI/OpenAPI-Specification
This commit should be treated as the Weles server "scaffolding"
The initial swagger.yml file is added so there is something to generate
the server from. "tbd" will be removed in future commits.
Server was generated using following command:
./dev-tools/swagger generate server \
-A weles \
-f ./swagger.yml \
-m ../weles \
-s ./server \
-r ./COPYING \
--flag-strategy pflag \
--compatibility-mode=modern
Due to agreed name of the server package ("server") there was a conflict in
names in generated code causng build error. Generated code used
server as a name for an object instance which has been renamed to srv.
The Makefile recipe has additional --exclude-main flag which prevents the
swagger generator from overwriting cmd/weles-server/main.go
This flag must be set because:
- obviously as stated above regenerating main will cause build error
- all Weles objects will have to be created there
- additional Weles flags will have to be added there
Thus overwriting this file is a no-no and server regeneration should
only be performed using provided Makefile recipe.
The Makefile has also a recipe to generate html documentation which is
intended to be integrated with Sphinx documentation. This recipe
requires docker:
https://docs.docker.com/get-started/
---
Verification
Update your vendor directory
$ make vendor
To build server:
$ make server
You can check default swagger generated server flags:
$ bin/weles-server --help
When the server is running you can also see how the automatically
served swagger documentation looks like:
http://{host:port}/docs
host and port are flags that should be supplied when running Weles.
If not provided, localhost and random port will be used.
To regenerate swagger server code:
$ make swagger-server-generate
To generate html documentation:
$ make swagger-docs-html
Change-Id: I00cda82219944cc6ab1937f6d14f05d52c7fd4e5
Signed-off-by: Alexander Mazuruk <a.mazuruk@samsung.com>
|
