This library currently only supports Basic and JWT, and will crash when provided with a route inside of an authenticate block using oauth. (No handler has been registered for (authenticate auth-oauth-google)). A workaround for projects using OAuth would be helpful.

OpenAPI supports constraints on data values https://swagger.io/docs/specification/data-models/data-types/

This should be supported by Kompendium

https://github.com/peter-evans/swagger-github-pages would be cool to integrate with kompendium so that an example is spun up via CI and then displayed

Hi,

This is great 💯 I was looking for a minimally invasive open api spec generator.
I need the support of security schemes (basic auth and jwt token).

That is, the security scheme would be added to the spec, for instance:

  "components" : {
    "securitySchemes" : {
      "basic_auth" : {
        "scheme" : "basic",
        "type" : "http"
      }
    }
  },

and that the scheme would be added where appropriate:

  "paths" : {
    "/api/v1/status" : {
      "get" : {
        "responses" : {
          "200" : {
            "description" : "OK"
          }
        },
        "security" : [ {
          "basic_auth" : [ ]
        } ]
      }
    },
 }

I was wondering if I could submit a PR for this. If so, do you have a particular api in mind?
I was thinking perhaps something like: notarizedAuthorization(name = "basic_auth") { .. }
This would be wrapper around Ktor's authentication method. The Kompendium object would then need to keep track of the current scheme that is in scope. What do you think?

would be cool :)

discussion here #64

Exception in thread "main" java.lang.IllegalStateException: Unknown selector (authenticate auth-jwt)
at io.bkbn.kompendium.path.CorePathCalculator.handleCustomSelectors(CorePathCalculator.kt:49)
at io.bkbn.kompendium.path.CorePathCalculator.calculate(CorePathCalculator.kt:44)
at io.bkbn.kompendium.path.CorePathCalculator.calculate(CorePathCalculator.kt:36)
at io.bkbn.kompendium.path.CorePathCalculator.calculate(CorePathCalculator.kt:36)
at io.bkbn.kompendium.path.CorePathCalculator.calculate(CorePathCalculator.kt:31)
at io.bkbn.kompendium.path.PathCalculator$DefaultImpls.calculate$default(PathCalculator.kt:13)

This occurs when trying to use the Authentication plugin's authorized block and include a notarized method inside. The crash occurs on server startup. I have verified that the Authentication Plugin is installed before Routing.

since Kompendium should be serializer agnostic, there should be a generalized test suite that is run against each of the common serializer libraries, proving that the results are as expected regardless of end user library choice

• Kotlinx Serialization
• Jackson
• Moshi
• Gson

For simplicities sake, MPV may only provide simple parameters

However, OpenAPI spec supports complex parameter types in a number of ways

Path parameters containing arrays and objects can be serialized in different ways:
path-style expansion (matrix) – semicolon-prefixed, such as /map/point;x=50;y=20
label expansion – dot-prefixed, such as /color.R=100.G=200.B=150
simple-style – comma-delimited, such as /users/12,34,56

For more info, see here https://swagger.io/docs/specification/describing-parameters/

Currently the packages are created on Github. Although I really like github workflow, serving the packages on Github can add a barrier to use it in other projects since it requires Github authentication (github community issue).

Currently I'm using Jitpack to retrieve it (example build log). But at the moment no releases are created so only git commit hash can be used, which works but I rather use the version as tag that is mentioned in the change log.

I was wondering if something like the following would be possible:

• deploy to maven central
  • I think that would be best as it easiest to integrate it on consuming projects.
  • This requires setting up an Sonatype account
• or, create releases on github when changelog has been changed on master

Or do you have other ideas? Happy to help to moving this forward 🚀

Not sure how this slipped through the V1 cracks but kompendium currently cannot process simple generics 😱

This is a very edgy edge case, but this

sealed interface SlammaJamma

data class OneJamma(val a: Int) : SlammaJamma
data class AnothaJamma(val b: Float) : SlammaJamma
data class InsaneJamma(val c: SlammaJamma) : SlammaJamma // 👀

will lead to a stack overflow. Fix it when u have some time

I am using https://orval.dev/ to generate react-query hooks based on the openapi.json file generated by Kompendium. Orval has support for using the OpenAPI "operationId" optional field to provide better names for the generated hooks.

From the Swagger docs:

operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

/users:
  get:
    operationId: getUsers
    summary: Gets all users
    ...
  post:
    operationId: addUser
    summary: Adds a new user
    ...
/user/{id}:
  get:
    operationId: getUserById
    summary: Gets a user by user ID
    ...
Some common use cases for operationId are:

Some code generators use this value to name the corresponding methods in code.
Links can refer to the linked operations by operationId.

It would be awesome if one could specify operationId as part of MethodInfo so it is generated as part of the openapi.json spec, something like this:

            MethodInfo.GetInfo(
                summary = "Get details of a dataset",
                responseInfo = ResponseInfo(HttpStatusCode.OK, "Details for a given dataset"),
                operationId = "getDatasetDetailsById"
            )

Now that dokka is officially in beta, I think it is stable enough to add it as the documentation engine for Kompendium :)

When documenting the root route, you get the following error

unknown selector type /
java.lang.IllegalStateException: unknown selector type /

The way that $ref works, there could only be a singular validation schema laid on top of a specific reference object. So a pretty huge refactor is going to be needed in order to allow for eventual validation implementation

Sealed classes show the sealed class information... need to grab implementing types and display accordingly

https://blog.jetbrains.com/ktor/2021/05/28/ktor-1-6-0-released/

That method is an absolute trainwreck. Fix it

Should allow devs to pass in an example data class to be used as an example in the documentation

it's really annoying that minor changes cause flips in json values, leading to false failures... find a tool to do a more intelligent json comparison than raw text

does not perform name overrides, and should provide capability to describe a field

There is a ton of code dup in the Gradle files, clean this up by creating some simple convention plugins that can be used across modules :)

Currently, the Route.redoc() extension function provides out of the box support for displaying docs using Redoc. It would be nice to offer out of the box swagger support as well, potentially in it's own module.

This one is most likely going to be a beast, I'm not quite sure how this is going to be feasible without directly coupling to a serialization framework or adding some very unwieldy annotations or reflections.

Setting as a V2 goal.

Would be cool to integrate this https://github.com/IBM/openapi-validator in order to run validations on a generated script. At least for snapshots in the test suite :)

I need to give X-UserEmail as a header key, but I can't, I couldn't configure the name of the request headers it takes whatever I give for the variable name as the key, please add configuration for it.
For example:
@KompendiumParam(ParamType.HEADER) val email: String
If we would have param like "name" I think it would be great because we can't create X-UserEmail as a variable name.

The only way I've found kompendium to mark a field optional is to have it nullable. However, one could in theory also use non-null fields with default values in data classes. When I do this they show up as required fields in Swagger. Is there a way to have them show as optional without marking them nullable?

Would be fantastic to explore integrating https://www.asyncapi.com with the ktor-websockets module to provide out of the box documentation for event-driven architectures.

Though kompendium supports sealed classes, documenting a collection of a sealed class does not generate as expected

I have a problem using notarizedExceptions for multiple exceptions with same status code, for example:

Endpoint can throw IllegalArgumentException and InvalidFormatException. Both exceptions should return 400 but the generated swagger document only shows the last notarizedException(within the statusPages module) with that status code.

I found this information about it. In Kompendium you are not allowed to pass a set of exceptions to a single notarized exception.

If your code can throw multiple exceptions, you would have to catch all of them and throw a generic exception. This generic exception would be the one that catches the notarizedException and inside its ResponseInfo is where you would put the different exception examples.

This solution I think is invasive and forces you to change your error handling.

Any other alternative?

Thanks a lot

From the open API spec

Default Parameter Values

Use the default keyword in the parameter schema to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request. The value type must be the same as the parameter’s data type. A typical example is paging parameters such as offset and limit

Needs to either work in conjunction with example parameters or act as a stand-in for that functionality.

Currently, path calculation is handled by an extensible interface PathCalculator... but as suggested in this thread #29 (comment) a more streamlined approached would be to allow for individual route selectors to be defined, and subsequently composed at runtime.

Would be great to get instant feedback on spec validation, perhaps using this library?

https://github.com/everit-org/json-schema

Since we reify the types, we are losing out on a ton of reflection capability by immediately converting to KClass. If we inspect the KType we should be able to offer top level enums, lists, etc. without impacting core functionality.

Need to add ability to parse parameters and append them to a requests specification

As shown by #75 the current type conversion is very fragile... should allow users to inject custom overrides so that hard coded types do not need to be added to handle every scenario.

It sounds like ktor 2 is coming with a ton of breaking changes. Will need to support these incoming updates.

Should be very simple to add runtime error if the declared path parameters do not meet the specification declared in the route itself.

Edit: I think a warn would be better... less opinionated.

Kompendium needs to support OpenAPI tags https://swagger.io/docs/specification/grouping-operations-with-tags in order to group API operations in a logical manner

Currently, UUID fields are parsed into a component schema as follows

"UUID": {
        "properties": {
          "mostSigBits": {
            "$ref": "#/components/schemas/Long"
          },
          "leastSigBits": {
            "$ref": "#/components/schemas/Long"
          }
        },
        "type": "object"
      }

This is wrong, and needs to instead be considered a base type, most likely extending String format with type uuid, see docs https://swagger.io/specification

type: string
format: uuid

Kompendium needs to allow for multiple responses so as to allow for things like error codes / responses along with happy path

I don't think annotations are the way to handle response codes.. maybe inline into the method info? advantage being easy way to add multiple statuses / responses, doesn't add weight to the data types, makes it easy to add response codes to things like generics, lists, and maps

Just food for thought

Unfortunately, github does not allow workflows to access secrets if triggered by a forked repo. So the code coverage will fail on any PR that is not initiated by yours truly.

Need to remove it from the PR workflow and only run from master.

Or maybe, if I can get really fancy, have a trigger that will check for any new branch to be opened up in this repo... that might work.

Request was made to support Java 8.. hopefully this will be as simple as changing the supported compile version, I don't believe any features of Kompedium are explicitly incompatible with Java 8

Hi!

Have you considered how support for Locations: https://ktor.io/docs/locations.html could be added to Kompendium?

I have a route like this:

route("organization") {
    notarizedGet(
        MethodInfo.GetInfo<CityIdQuery, List<OrganizationDto>>(
            summary = "Get organizations",
            tags = setOf("dicts"),
            responseInfo = ResponseInfo(
                status = HttpStatusCode.OK,
                description = "",
            )
        )
    ) {
        ...
    }
}

and OrganizationDto class is like this:

data class OrganizationDto(
  val id: UUID,
  val commission: BigDecimal? = null,
  ...
)

Whenever I run the project I get an exception:

Caused by: java.lang.IllegalStateException: Unable to parse field type from val kotlin.IntArray.size: kotlin.Int
	at io.bkbn.kompendium.Kontent.handleComplexType(Kontent.kt:141)
	at io.bkbn.kompendium.Kontent.access$handleComplexType(Kontent.kt:30)
	at io.bkbn.kompendium.Kontent$generateKTypeKontent$2.invoke(Kontent.kt:113)
	at io.bkbn.kompendium.Kontent$generateKTypeKontent$2.invoke(Kontent.kt:98)
	at io.bkbn.kompendium.util.Helpers.logged(Helpers.kt:26)

This is because of this line:

object Kontent {
  ...
  val field = prop.javaField?.type?.kotlin ?: error("Unable to parse field type from $prop")
  ...
}