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

./gradlew run

## show lint errors
./gradlew lintKotlin

## Attempt to auto fix lint errors
./gradlew formatKotlin

./gradlew test

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

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

License

Apache 2