{"id":14973023,"url":"https://github.com/qaware/openapi-generator-for-spring","last_synced_at":"2025-03-22T17:07:17.094Z","repository":{"id":37828615,"uuid":"317148873","full_name":"qaware/openapi-generator-for-spring","owner":"qaware","description":"Open API v3 Generator for Spring Boot applications","archived":false,"fork":false,"pushed_at":"2024-09-16T04:37:30.000Z","size":2179,"stargazers_count":74,"open_issues_count":20,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-14T19:02:48.123Z","etag":null,"topics":["hacktoberfest","java","openapi","spring","spring-boot","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-30T07:52:05.000Z","updated_at":"2024-10-12T18:03:15.000Z","dependencies_parsed_at":"2024-11-16T01:14:48.503Z","dependency_job_id":null,"html_url":"https://github.com/qaware/openapi-generator-for-spring","commit_stats":{"total_commits":638,"total_committers":8,"mean_commits":79.75,"dds":"0.25705329153605017","last_synced_commit":"66aeab753e49ba7cb7454da688b830fbaa38e2a5"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fopenapi-generator-for-spring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fopenapi-generator-for-spring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fopenapi-generator-for-spring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fopenapi-generator-for-spring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qaware","download_url":"https://codeload.github.com/qaware/openapi-generator-for-spring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244991166,"owners_count":20543627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","java","openapi","spring","spring-boot","swagger"],"created_at":"2024-09-24T13:47:57.676Z","updated_at":"2025-03-22T17:07:17.060Z","avatar_url":"https://github.com/qaware.png","language":"Java","readme":"# OpenAPI v3 generator for Spring Boot\n\n[![Build Status](https://github.com/qaware/openapi-generator-for-spring/workflows/build/badge.svg?branch=master)](https://github.com/qaware/openapi-generator-for-spring/actions?query=workflow%3A%22build%22)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=qaware_openapi-generator-for-spring\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=qaware_openapi-generator-for-spring)\n[![Code Coverage](https://sonarcloud.io/api/project_badges/measure?project=qaware_openapi-generator-for-spring\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=qaware_openapi-generator-for-spring)\n[![Maven Central](https://img.shields.io/maven-central/v/de.qaware.tools.openapi-generator-for-spring/openapi-generator-for-spring-starter)](https://mvnrepository.com/artifact/de.qaware.tools.openapi-generator-for-spring/openapi-generator-for-spring-starter)\n\nThis library automagically generates a [OpenApi v3 specification](https://github.com/OAI/OpenAPI-Specification) at\nruntime for [Spring Boot](https://spring.io/projects/spring-boot) applications.\n\nIt aims at fully analyzing Spring request mappings augmented by Swagger annotations to provide a self-descriptive API\nspecification of your application.\n\n## Features\n\n* Spring WebMVC support including content negotiation support\n* Spring WebFlux support\n  including [Router Functions](https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html#webflux-fn)\n* Integrated [Swagger UI](https://github.com/swagger-api/swagger-ui)\n* [Swagger Annotations v3](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-annotations) support\n* No dependency on\n  [swagger-core module](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-core)\n  or\n  [swagger-models module](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models)\n* Extended support for `Schema` building, including self-referencing types\n  and [Jackson polymorphism](https://github.com/FasterXML/jackson-docs/wiki/JacksonPolymorphicDeserialization)\n\nNote that some features are not fully implemented yet,\nsee [issues](https://github.com/qaware/openapi-generator-for-spring/issues).\n\n## Getting started\n\nInside your Spring Boot application, add the following (maven) dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.qaware.tools.openapi-generator-for-spring\u003c/groupId\u003e\n    \u003cartifactId\u003eopenapi-generator-for-spring-starter\u003c/artifactId\u003e\n    \u003cversion\u003e6.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nAfter starting your application, the OpenApi v3 specification of your application is provided at `/v3/api-docs` as JSON.\nThis specification can be viewed by visiting `/swagger-ui` inside your browser (relative to context path).\n\nHave a look at the\n[Demo for WebMVC](demo/openapi-generator-for-spring-demo-webmvc)\nand\n[Demo for WebFlux](demo/openapi-generator-for-spring-demo-webflux)\nfor a first impression.\n\n## Configuration Properties\n\nThe following configuration properties are available with the prefix `openapi-generator-for-spring.`:\n\n* [Open API Properties](openapi-generator-for-spring-common/src/main/java/de/qaware/openapigeneratorforspring/common/OpenApiConfigurationProperties.java)\n* [Open API Info Properties](openapi-generator-for-spring-common/src/main/java/de/qaware/openapigeneratorforspring/common/info/OpenApiInfoConfigurationProperties.java)\n* [Open API Swagger UI Properties](openapi-generator-for-spring-ui/src/main/java/de/qaware/openapigeneratorforspring/ui/OpenApiSwaggerUiConfigurationProperties.java)\n\nThe following extension properties are currently part of this library:\n\n* [Java8 Time](openapi-generator-for-spring-common/src/main/java/de/qaware/openapigeneratorforspring/common/schema/resolver/type/extension/java8/Java8TimeTypeResolverConfigurationProperties.java)\n\n## How To\n\n### How to filter paths, operations and parameters within the specification?\n\nThe library supports filtering at the following stages during OpenApi specification building, in this order:\n\n1. [HandlerMethodFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/handlermethod/HandlerMethodFilter.java)\n   filters before passing on the found handler methods to the path building.\n1. [OperationPreFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/operation/OperationPreFilter.java)\n   filters before the `Operation` model object is built.\n1. [OperationParameterPreFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/operation/parameter/OperationParameterPreFilter.java)\n   filters before a `Parameter` model object of an operation is built.\n1. [OperationParameterPostFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/operation/parameter/OperationParameterPostFilter.java)\n   filters after a `Parameter` has been built.\n1. [OperationPostFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/operation/OperationPostFilter.java)\n   filters after a `Operation` has been built. All information has been set except referenced components.\n1. [PathItemFilter](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/filter/pathitem/PathItemFilter.java)\n   filters after a `PathItem` is fully constructed. All information has been set except referenced components.\n\nInsert a bean extending one or more of the above interfaces, which will be picked up by the library.\n\nThe later the filter is called the more work has been done, but also more information is supplied to make the filtering\ndecision. Possibly referenced components must be manually cleared later on in an extra customization step if filtering\nhappened too late. It is thus recommended applying filtering as early as possible.\n\n### How to obtain a grouped OpenAPI specification?\n\nGrouping is realized by applying filters, preferably a `OperationPreFilter`, while building the OpenAPI specification.\nQuery and header parameters of the HTTP request to `/v3/api-docs` can be obtained within the filter by auto-wiring the\nbean of type `OpenApiRequestParameterProvider`.\n\nThis way, you can control which operations are considered for the specification when `/v3/api-docs?group=MyGroup`. The\nSwagger UI can also be customized to display more than one specification by providing a bean of type\n`OpenApiSwaggerUiApiDocsUrisSupplier`.\n\nSee the `*Configuration` class of this\n[integration test](openapi-generator-for-spring-test/src/test/java/de/qaware/openapigeneratorforspring/test/app10)\nor this\n[integration test](openapi-generator-for-spring-test/src/test/java/de/qaware/openapigeneratorforspring/test/app18)\nfor a fully working WebMVC or WebFlux example, respectively. Note that the test cases invoke the endpoint with different\nheader or query parameters.\n\n### How to customize the specification?\n\nThe library offers various customizers, which allow the library user to (hopefully) adapt to any use case which comes to\nmind.\n\nThe following shows some examples for customizers:\n\n* [SchemaCustomizer](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/schema/customizer/SchemaCustomizer.java)\n  customizes a constructed\n  [Schema](openapi-generator-for-spring-model/src/main/java/de/qaware/openapigeneratorforspring/model/media/Schema.java)\n  . An example is the\n  [SchemaCustomizerForNullable](openapi-generator-for-spring-common/src/main/java/de/qaware/openapigeneratorforspring/common/schema/customizer/SchemaCustomizerForNullable.java)\n  .\n* [OperationCustomizer](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common/operation/customizer/OperationCustomizer.java)\n  customizes a constructed\n  [Operation](openapi-generator-for-spring-model/src/main/java/de/qaware/openapigeneratorforspring/model/operation/Operation.java)\n  . An example is\n  the [DefaultOperationIdCustomizer](openapi-generator-for-spring-common/src/main/java/de/qaware/openapigeneratorforspring/common/operation/customizer/DefaultOperationIdCustomizer.java)\n  which sets the Operation ID from an\n  [OperationIdProvider]() bean.\n* This\n  [integration test](openapi-generator-for-spring-test/src/test/java/de/qaware/openapigeneratorforspring/test/app9/App9Configuration.java)\n  shows an example how to override the default identifier when referencing request bodies.\n\nFeel free to investigate the\n[api module](openapi-generator-for-spring-api/src/main/java/de/qaware/openapigeneratorforspring/common)\nfor more details. The relevant interfaces all have the suffix `Customizer` and extend the `Ordered` interface.\n\n#### Examples\n\n`OperationCustomizer` bean that uses the class name of the RestController to set it as OpenAPI tag\n\n```java\n/**\n * Provide an OperationCustomizer to use the class name of the REST controller as Tag. This way the API endpoints are grouped per REST controller.\n *\n * @return OperationCustomizer\n */\n@Bean\npublic OperationCustomizer operationTagCustomizer() {\n    return (operation, operationBuilderContext) -\u003e {\n        if (CollectionUtils.isEmpty(operation.getTags())) {\n            operationBuilderContext.getHandlerMethod(SpringWebHandlerMethod.class).ifPresent(handlerMethod -\u003e {\n                String declaringClassName = handlerMethod.getMethod().getMethod().getDeclaringClass().getSimpleName();\n                operation.setTags(singletonList(declaringClassName));\n                operationBuilderContext.getReferencedItemConsumer(ReferencedTagsConsumer.class)\n                        .accept(singletonList(Tag.builder().name(declaringClassName).build()));\n            });\n        }\n    };\n}\n```\n\n`OperationIdProvider` to generate deep-links to specific endpoints that are compatible to the SpringFox style\n\n```java\n/**\n * Provide an OperationIdProvider to generate deep-links that are compatible to the SpringFox style.\n *\n * @return OperationIdProvider\n */\n@Bean\npublic OperationIdProvider operationIdProvider() {\n    return operationInfo -\u003e operationInfo.getHandlerMethod().getIdentifier() + \"Using\" + operationInfo.getRequestMethod().name();\n}\n```\n\n### How to customize the included Swagger UI?\n\nThe Swagger UI `index.html` is generated from a\n[Mustache template](openapi-generator-for-spring-ui/src/main/resources/swagger-ui/index.html.mustache)\nand uses the\n[Swagger UI Webjar](https://github.com/webjars/swagger-ui)\ndistribution.\n\nThe default implementation of\n[OpenApiSwaggerUiApiDocsUrisSupplier](openapi-generator-for-spring-ui/src/main/java/de/qaware/openapigeneratorforspring/ui/OpenApiSwaggerUiApiDocsUrisSupplier.java)\nuses the given URI to the API Docs endpoint and names the entry `Default`. This name is ignored as there is only one\nentry in the Swagger UI.\n\nSee this\n[integration test](openapi-generator-for-spring-test/src/test/java/de/qaware/openapigeneratorforspring/test/app10/App10Configuration.java)\nfor an example how to customize the offered API Docs within the Swagger UI.\n\n### How to substitute a type for Schema resolution?\n\nDefine the following bean of type `InitialTypeBuilder` if you want to resolve the type `YourType` always as if it was of\ntype `String`:\n\n```java\n@Bean\npublic InitialTypeBuilder openApiSchemaTypeSubstitutionForYourType(){\n        return(caller,javaType,annotationsSupplier,recursiveBuilder)-\u003e{\n        if(javaType.getRawClass().equals(YourType.class)){\n            return recursiveBuilder.build(String.class, annotationsSupplier);\n        }\n        return null;\n    };\n}\n```\n\n### How to handle error responses elegantly?\n\nSpring (Boot) offers to handle exceptions from handler methods via\n`@ExceptionHandler` annotated methods. This mechanism can be plugged into the specification by using\nan `OperationCustomizer`, which scans a `SpringWebHandlerMethod` for its exception signature and adds\nadditional `ApiResponse`s to the `Operation` for each exception.\n\nOne can even figure out the `@ExceptionHandler` method, as Spring would do, to automatically determine the `Schema` of\nthe error response and also scan for `@ReponseStatus` to determine the error code.\n\nIt is also possible to throw an error when there is an exception declared but no appropriate `@ExceptionHandler` method\nis found.\n\nSee [this configuration of the integration test](openapi-generator-for-spring-test/src/test/java/de/qaware/openapigeneratorforspring/test/app32/App32Configuration.java)\nfor a fully worked out example.\n\n## Why not another library?\n\nThis library is based on experience while using [Spring Fox](https://github.com/springfox/springfox)\nand [SpringDoc OpenApi](https://github.com/springdoc/springdoc-openapi). As those libraries have turned out to be not\nflexible enough for our internal projects, this library aims at being fully customizable.\n\nComposing Spring beans in combination with Spring Boot autoconfiguration enable this flexibility. The library offers\nopinionated (and hopefully sane) default implementations but marks all of them with `@ConditionalOnMissingBean`. It is\nencouraged to override those defaults by providing own bean implementations.\n\nDefault implementations in `common` module will use the `api`\nmodule interfaces as much as possible. This way it is ensured that the provided api module actually offers useful\ninterfaces.\n\n## Module structure\n\nAll the following module names are prefixed with `openapi-generator-for-spring-`.\n\n**[model](openapi-generator-for-spring-model)** contains Jackson-serializable POJOs to represent\nthe [OpenApi v3 model](https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md).\n\n**[api](openapi-generator-for-spring-api)** contains the public API to extend and adapt the functionality of this\nlibrary.\n\n**[common](openapi-generator-for-spring-common)** contains the main algorithm parsing the swagger-annotated handler\nmethods. It provides default implementations for most of the interfaces in `openapi-generator-for-spring-api` module.\n\n**[autoconfigure](openapi-generator-for-spring-autoconfigure)** contains the Spring Boot auto-configuration of common\nbeans.\n\n**[web](openapi-generator-for-spring-web)** shared support code for Spring WebMVC and WebFlux including shared\nauto-configuration.\n\n**[webmvc](openapi-generator-for-spring-webmvc)** supports Spring WebMVC via Spring Boot auto-configuration.\n\n**[webflux](openapi-generator-for-spring-webflux)** supports Spring WebFlux via Spring Boot auto-configuration.\n\n**[ui](openapi-generator-for-spring-ui)** Provides Swagger UI below `/swagger-ui`. Offers UI Resource transformation for\nWebMVC and WebFlux and sets up correct redirect routes.\n\n**[starter](openapi-generator-for-spring-starter)** Opinionated choice of dependencies. Enables Swagger UI and support\nfor WebMVC and WebFlux if present.\n\n**[test](openapi-generator-for-spring-test)** contains all integration tests for WebMVC and WebFlux.\n\n**[shaded](openapi-generator-for-spring-shaded)** contains shaded dependencies to avoid interference with Spring Boot\nautoconfiguration. This library does not want to trigger Mustache or WebJar exposure for users of this library. Shading\nis the only mechanism which still allows to use such code but hide it from Spring Boot.\n\nEach module aims to have minimal dependencies. General library dependencies are:\n\n* Spring Core (Web/WebMVC/WebFlux are optional)\n* Jackson\n* Swagger Annotations\n* WebJar for Swagger UI (shaded)\n* Mustache (shaded)\n* Apache Commons\n\n## Development \u0026 Contributing\n\nPlease open an issue before posting a pull request unless you have a very obvious fix or improvement to contribute.\n\nWhen developing with IntelliJ, run `mvn clean package -DskipTests` first in order to get the integration tests also\nrunning from within the IDE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fopenapi-generator-for-spring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqaware%2Fopenapi-generator-for-spring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fopenapi-generator-for-spring/lists"}