Skip to content

Commit

Permalink
Merge branch 'develop' into release
Browse files Browse the repository at this point in the history
  • Loading branch information
SMILEY4 committed Jun 9, 2024
2 parents 425236e + 9062dae commit 615fe6f
Show file tree
Hide file tree
Showing 189 changed files with 5,218 additions and 7,276 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ jobs:
- name: Publish
run: |
./gradlew publishAllPublicationsToMavenCentral --no-configuration-cache
./gradlew closeAndReleaseRepository
./gradlew releaseRepository
env:
SONATYPE_CONNECT_TIMEOUT_SECONDS: 180
SONATYPE_CLOSE_TIMEOUT_SECONDS: 900
Expand Down
9 changes: 0 additions & 9 deletions HowToRelease.md

This file was deleted.

26 changes: 16 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,19 @@
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.smiley4/ktor-swagger-ui/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.smiley4/ktor-swagger-ui)
[![Checks Passing](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml/badge.svg?branch=develop)](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml)


This library provides a Ktor plugin to document routes, generate an OpenApi Specification and serve a Swagger UI. It is meant to be minimally invasive, meaning it can be plugged into existing application without requiring immediate changes to the code. Routes can then be gradually enhanced with documentation.


## Features

- minimally invasive (no immediate change to existing code required)
- provides swagger-ui with no initial configuration required
- supports most of the [OpenAPI 3.0.3 Specification](https://swagger.io/specification/)
- automatic json-schema generation from arbitrary types/classes for bodies and parameters
- use custom encoder/serializers for examples and json-schemas
- provide custom schemas or a custom schema-builder
- external/custom json-schemas for bodies
- protect Swagger-UI and OpenApi-Spec with custom authentication
- provides swagger-ui and openapi-spec with minimal configuration
- supports most of the [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)
- automatic [json-schema generation](https://github.com/SMILEY4/schema-kenerator) from arbitrary types/classes for bodies and parameters
- supports generics, inheritance, collections, ...
- support for Jackson-annotations and swagger Schema-annotations (optional)
- use with reflection or kotlinx-serialization
- customizable schema-generation


## Documentation
Expand All @@ -32,9 +31,14 @@ dependencies {
}
```

## Example
Full examples can be found in [src/test/examples](https://github.com/SMILEY4/ktor-swagger-ui/tree/develop/src/test/kotlin/io/github/smiley4/ktorswaggerui/examples).

## Examples

Runnable examples can be found in [ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples](https://github.com/SMILEY4/ktor-swagger-ui/tree/release/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples).


### Configuration

```kotlin
install(SwaggerUI) {
swagger {
Expand All @@ -52,7 +56,9 @@ install(SwaggerUI) {
}
}
```

### Routes

```kotlin
get("hello", {
description = "Hello World Endpoint."
Expand Down
136 changes: 6 additions & 130 deletions build.gradle.kts
Original file line number Diff line number Diff line change
@@ -1,135 +1,11 @@
import com.vanniktech.maven.publish.SonatypeHost
import io.gitlab.arturbosch.detekt.Detekt

object Meta {
const val groupId = "io.github.smiley4"
const val artifactId = "ktor-swagger-ui"
const val version = "2.10.0"
const val name = "Ktor Swagger-UI"
const val description = "Ktor plugin to document routes and provide Swagger UI"
const val licenseName = "The Apache License, Version 2.0"
const val licenseUrl = "https://www.apache.org/licenses/LICENSE-2.0.txt"
const val scmUrl = "https://github.com/SMILEY4/ktor-swagger-ui"
const val scmConnection = "scm:git:git://github.com/SMILEY4/ktor-swagger-ui.git"
const val developerName = "smiley4"
const val developerUrl = "https://github.com/SMILEY4"
}

group = Meta.groupId
version = Meta.version

plugins {
kotlin("jvm") version "1.8.21"
kotlin("plugin.serialization") version "1.8.21"
id("org.owasp.dependencycheck") version "8.2.1"
id("com.vanniktech.maven.publish") version "0.25.2"
id("io.gitlab.arturbosch.detekt") version "1.23.0"
kotlin("jvm") version "1.9.21"
id("org.jetbrains.dokka") version "1.9.20" apply false
id("org.owasp.dependencycheck") version "8.2.1" apply false
id("io.gitlab.arturbosch.detekt") version "1.23.0" apply false
id("com.vanniktech.maven.publish") version "0.28.0" apply false
}

repositories {
mavenCentral()
maven(url = "https://raw.githubusercontent.com/glureau/json-schema-serialization/mvn-repo")
}

dependencies {

val ktorVersion = "2.3.7"
implementation("io.ktor:ktor-server-core-jvm:$ktorVersion")
implementation("io.ktor:ktor-server-webjars:$ktorVersion")
implementation("io.ktor:ktor-server-auth:$ktorVersion")
implementation("io.ktor:ktor-server-resources:$ktorVersion")
testImplementation("io.ktor:ktor-server-netty-jvm:$ktorVersion")
testImplementation("io.ktor:ktor-server-content-negotiation:$ktorVersion")
testImplementation("io.ktor:ktor-serialization-jackson:$ktorVersion")
testImplementation("io.ktor:ktor-server-auth:$ktorVersion")
testImplementation("io.ktor:ktor-server-call-logging:$ktorVersion")
testImplementation("io.ktor:ktor-server-test-host:$ktorVersion")

val swaggerUiVersion = "5.9.0" // this version must match the version declared in the code (SwaggerPlugin#SWAGGER_UI_WEBJARS_VERSION)
implementation("org.webjars:swagger-ui:$swaggerUiVersion")

val swaggerParserVersion = "2.1.19"
implementation("io.swagger.parser.v3:swagger-parser:$swaggerParserVersion")

val jsonSchemaGeneratorVersion = "4.33.1"
implementation("com.github.victools:jsonschema-generator:$jsonSchemaGeneratorVersion")
implementation("com.github.victools:jsonschema-module-jackson:$jsonSchemaGeneratorVersion")
implementation("com.github.victools:jsonschema-module-swagger-2:$jsonSchemaGeneratorVersion")

val jacksonVersion = "2.15.3"
implementation("com.fasterxml.jackson.module:jackson-module-kotlin:${jacksonVersion}")

val kotlinLoggingVersion = "3.0.5"
implementation("io.github.microutils:kotlin-logging-jvm:$kotlinLoggingVersion")

val logbackVersion = "1.4.11"
testImplementation("ch.qos.logback:logback-classic:$logbackVersion")

val versionMockk = "1.13.8"
testImplementation("io.mockk:mockk:$versionMockk")

val versionKotest = "5.8.0"
testImplementation("io.kotest:kotest-runner-junit5:$versionKotest")
testImplementation("io.kotest:kotest-assertions-core:$versionKotest")

val versionKotlinTest = "1.8.21"
testImplementation("org.jetbrains.kotlin:kotlin-test:$versionKotlinTest")

testImplementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
testImplementation("com.github.Ricky12Awesome:json-schema-serialization:0.9.9")
testImplementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.1")
}

kotlin {
jvmToolchain(11)
}

tasks.withType<Test>().configureEach {
useJUnitPlatform()
}

detekt {
buildUponDefaultConfig = true
allRules = false
config.setFrom("$projectDir/config/detekt.yml")
baseline = file("$projectDir/config/baseline.xml")
}

tasks.withType<Detekt>().configureEach {
reports {
html.required.set(true)
md.required.set(true)
xml.required.set(false)
txt.required.set(false)
sarif.required.set(false)
}
}

mavenPublishing {
publishToMavenCentral(SonatypeHost.S01)
signAllPublications()
coordinates(Meta.groupId, Meta.artifactId, Meta.version)
pom {
name.set(Meta.name)
description.set(Meta.description)
url.set(Meta.scmUrl)
licenses {
license {
name.set(Meta.licenseName)
url.set(Meta.licenseUrl)
distribution.set(Meta.licenseUrl)
}
}
scm {
url.set(Meta.scmUrl)
connection.set(Meta.scmConnection)
}
developers {
developer {
id.set(Meta.developerName)
name.set(Meta.developerName)
url.set(Meta.developerUrl)
}
}
}
}
}
Loading

0 comments on commit 615fe6f

Please sign in to comment.