Awesome

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):

<table> <tr> <td align="center"><a href="https://github.com/katielevy1"><img src="https://avatars0.githubusercontent.com/u/8975181?v=4" width="100px;" alt=""/> Katie Levy</a> <a href="https://github.com/cdimascio/kotlin-openapi-spring-functional-template/commits?author=katielevy1" title="Code">💻</a></td> <td align="center"><a href="https://about.me/naxa"><img src="https://avatars0.githubusercontent.com/u/3858548?v=4" width="100px;" alt=""/> Paul</a> <a href="https://github.com/cdimascio/kotlin-openapi-spring-functional-template/commits?author=naXa777" title="Documentation">📖</a></td> <td align="center"><a href="https://ibragimov.by/"><img src="https://avatars0.githubusercontent.com/u/493656?v=4" width="100px;" alt=""/> Ibragimov Ruslan</a> <a href="https://github.com/cdimascio/kotlin-openapi-spring-functional-template/commits?author=IRus" title="Code">💻</a></td> <td align="center"><a href="https://github.com/ChristofBuechi"><img src="https://avatars1.githubusercontent.com/u/2494089?v=4" width="100px;" alt=""/> Christof</a> <a href="https://github.com/cdimascio/kotlin-openapi-spring-functional-template/commits?author=ChristofBuechi" title="Code">💻</a></td> </tr> </table>

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Apache 2