kotlin-swagger-spring-functional
A project template for Kotlin Spring WebFlux. The template features automatic request validation and interactive API documentation using an OpenApi 3.0 or Swagger 2.0 specification. The template provides 12-factor compliant environment based config and integrated in linting.
What's included?
- Automatic request validation via openapi-spring-webflux-validator
- Custom error responses via openapi-spring-webflux-validator
- Environment based config via java-dotenv
- Interactive API documentation via Swagger UI
- Automatic linting via ktlint
Request validation and interactive documentation are based on an OpenApi 3.0 or Swagger v2 API specification. The specification is located at main/resources/static/api.yaml
.
Install
Clone this repo
Build
./gradlew build
Run
./gradlew run
Lint
## show lint errors
./gradlew lintKotlin
## Attempt to auto fix lint errors
./gradlew formatKotlin
Test
./gradlew test
Dist
./gradlew clean distZip
Output artifact located at build/distributions
or unpacked
./gradlew clean distZip unzip
Output artifact located at build/unpacked/dist
Run the standalone dist
Create an unpacked dist. See the Dist section above. Then run it
cp build/unpacked/dist $HOME/kotlin-swagger-spring-functional-1.0.0/bin/kotlin-swagger-spring-functional
Try It!
Run the app or run the standalone dist, then:
curl http://localhost:8080/api/users
Try the example endpoints (with swagger validation)
POST to /users
with a valid request body
curl -X POST http://localhost:8080/api/users -H "Content-Type: application/json" -d '{ "firstname": "carmine", "lastname": "dimascio" }'
result
{
"firstname":"carmine",
"lastname":"dimascio"
}
POST to /users
with an invalid request body i.e. we leave off the required field lastname
curl -X POST http://localhost:8080/api/users -H "Content-Type: application/json" -d '{ "firstname": "carmine" }'
result
{
"errors":[{
"code":"bad_request",
"message":"Object has missing required properties ([\"lastname\"])"}
]}
Try the Interactive API documentation
Navigate to http://localhost:8080
โจ
Contributors Thanks goes to these wonderful people (emoji key):
Katie Levy |
Paul ๐ |
Ibragimov Ruslan |
Christof |
This project follows the all-contributors specification. Contributions of any kind welcome!