https://github.com/cdimascio/kotlin-openapi-spring-functional-template
🍃 Kotlin Spring 5 Webflux functional application with api request validation and interactive api doc
https://github.com/cdimascio/kotlin-openapi-spring-functional-template
functional hacktoberfest kotlin kotlin-spring-webflux rest spring swagger template validation webflux
Last synced: 7 months ago
JSON representation
🍃 Kotlin Spring 5 Webflux functional application with api request validation and interactive api doc
- Host: GitHub
- URL: https://github.com/cdimascio/kotlin-openapi-spring-functional-template
- Owner: cdimascio
- License: other
- Created: 2017-11-30T22:22:32.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-04-21T02:59:09.000Z (over 5 years ago)
- Last Synced: 2025-05-10T23:04:15.848Z (7 months ago)
- Topics: functional, hacktoberfest, kotlin, kotlin-spring-webflux, rest, spring, swagger, template, validation, webflux
- Language: Kotlin
- Homepage: https://dzone.com/articles/build-rest-apis-with-kotlin-spring-5-webflux-and-p
- Size: 4.16 MB
- Stars: 183
- Watchers: 5
- Forks: 50
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/cdimascio/openapi-spring-webflux-validator)
* Custom error responses via [openapi-spring-webflux-validator](https://github.com/cdimascio/openapi-spring-webflux-validator)
* Environment based config via [java-dotenv](https://github.com/cdimascio/java-dotenv)
* Interactive API documentation via [Swagger UI](https://swagger.io/swagger-ui/)
* Automatic linting via [ktlint](ktlint.github.io)
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
```shell
./gradlew build
```
## Run
```shell
./gradlew run
```
## Lint
```shell
## show lint errors
./gradlew lintKotlin
## Attempt to auto fix lint errors
./gradlew formatKotlin
```
## Test
```shell
./gradlew test
```
## Dist
```shell
./gradlew clean distZip
```
Output artifact located at `build/distributions`
or unpacked
```shell
./gradlew clean distZip unzip
```
Output artifact located at `build/unpacked/dist`
## Run the standalone dist
Create an unpacked dist. See the [Dist](#dist) section above. Then run it
```shell
cp build/unpacked/dist $HOME/kotlin-swagger-spring-functional-1.0.0/bin/kotlin-swagger-spring-functional
```
## Try It!
[Run](#run) the app or run the [standalone dist](#run-the-standalone-dist), then:
```xml
curl http://localhost:8080/api/users
```
### Try the example endpoints (with swagger validation)
POST to `/users` with a *valid* request body
```shell
curl -X POST http://localhost:8080/api/users -H "Content-Type: application/json" -d '{ "firstname": "carmine", "lastname": "dimascio" }'
```
result
```json
{
"firstname":"carmine",
"lastname":"dimascio"
}
```
POST to `/users` with an *invalid* request body i.e. we leave off the required field `lastname`
```shell
curl -X POST http://localhost:8080/api/users -H "Content-Type: application/json" -d '{ "firstname": "carmine" }'
```
result
```json
{
"errors":[{
"code":"bad_request",
"message":"Object has missing required properties ([\"lastname\"])"}
]}
```
### Try the Interactive API documentation
Navigate to [http://localhost:8080](http://localhost:8080)
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Katie Levy
💻
Paul
📖
Ibragimov Ruslan
💻
Christof
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## License
[Apache 2](LICENSE)
