Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/juntaki/springfennec
Swagger spec generator from Spring annotations, written in Kotlin
https://github.com/juntaki/springfennec
kotlin spring-boot swagger swagger-codegen
Last synced: 5 days ago
JSON representation
Swagger spec generator from Spring annotations, written in Kotlin
- Host: GitHub
- URL: https://github.com/juntaki/springfennec
- Owner: juntaki
- License: apache-2.0
- Created: 2017-09-09T08:07:54.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-09-28T02:00:25.000Z (over 7 years ago)
- Last Synced: 2024-11-16T03:27:02.246Z (3 months ago)
- Topics: kotlin, spring-boot, swagger, swagger-codegen
- Language: Kotlin
- Homepage:
- Size: 206 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Springfennec
[](https://maven-badges.herokuapp.com/maven-central/com.juntaki/springfennec)
[Swagger (OpenAPI 2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) spec.json generator for the API client generation by [swagger-codegen](https://github.com/swagger-api/swagger-codegen).
## Features
mainly compared with [Springfox](http://springfox.github.io/springfox/).
* Predictable OperationId. build will fail if it isn't unique.
* No duplicate of model name
* Output spec.json as a file at build, server start isn't required.
* Spring annotation than Swagger annotation, focus on the actual behaviour.
You cannot do the following only with springfennec. Use [swagger-ui](https://github.com/swagger-api/swagger-ui).
* Hosting swagger-ui in App
Although Springfennec supports basic (as I think) Spring functionality, but it still cannot cover all of it.
Please make a request by Pull request or Issue.
## How to work
### OperationId
If nickname in @ApiOperation annotation is defined, it will be OperationId. If not, function name will be used.
In order to generate a predictable OperationId, programmer have the responsibility to maintain its uniqueness. Therefore, suffix are not added by springfennec. If it isn't unique in the API group, the build will just fail.
### Model name
Model name is Java FQCN, so it's always unique.
## How to use
### Get started
Please refer to [springfennec-demo](https://github.com/juntaki/springfennec-demo) Project.
Use apt or kapt to work Springfennec at build.
Add the following line to build.Gradle's dependencies.
If you are working with Java only project, add Kotlin dependency also.
~~~
dependencies {
...
// Springfennec
def springfennecVersion = 'x.x.x'
compile('io.swagger:swagger-core:1.5.16')
compile("com.juntaki:springfennec:${springfennecVersion}")
kapt("com.juntaki:springfennec:${springfennecVersion}")
...
}
~~~
### Springfennec annotation
You can define multiple API groups in an App, by @ApiGroup/@ApiGroups annotations. (like Docket)
OperationId must be unique for each API group.
For @SwaggerDefinition annotation, refer to [Swagger-Core Annotations documentation](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#swaggerdefinition)
~~~
@ApiGroup(value="^/pet/.*", // regex for path (not include basePath)
name = "pet_api", // output will be spec_${name}.json, e.g. spec_pet_api.json
apiInfo = @SwaggerDefinition(...))
~~~
e.g. ApiGroups example
~~~
@ApiGroups(
arrayOf(
ApiGroup(arrayOf("^/demo/user.*"),
name = "user",
apiInfo = SwaggerDefinition(
info = Info(
version = "1.0",
title = "User API"
)
)
),
ApiGroup(arrayOf("^/demo/admin.*"),
name = "admin",
apiInfo = SwaggerDefinition(
info = Info(
version = "1.0",
title = "Admin API"
)
)
)
)
)
~~~
### Swagger annotation
The following swagger annotation is used for spec.json generation.
Parameters determined by Spring may be ignored, even if the annotation defines it.
~~~
@ApiOperation
@ApiParam
~~~