Implement Source DocumentationProvider, `spring-mvc` decommission #11531

cachescrubber · 2022-02-05T18:27:38Z

Finish the DocumentationProvider Story (#11258)

Changes

When source is selected as DocumentationProvider, the original openapi spec is copied to the project and
is exposed via /openapi.{json,yaml}. Swagger-ui, if enabled, is configured to show this spec.

SpringCodegen now implements SwaggerUIFeatures. Use the useSwaggerUI parameter with the spring-boot library to use it. Swagger UI is enabled by default.
Upgrade swagger-ui to 4.4.1 including a customised swagger-ui.html
The SpringBootApplication class is renamed to OpenApiGeneratorApplication.java.
Introduce SpringBootTest.mustache as OpenApiGeneratorApplicationTests.java.
Remove option openapiDocketConfig. Replaced by documentationProvider=springfox.

Deprecation Warnings

springfox (documentationProvider): Springfox is deprecated for removal in version 7.0.0 of openapi-generator. The project seems to be no longer maintained (last commit is of Oct 14, 2020). It works with Spring Boot 2.5.x but not with 2.6. Spring Boot 2.5 is supported until 2022-05-19. Users of openapi-generator should migrate to the springdoc documentation provider which is, as an added bonus, OpenAPI v3 compatible.

Removals

spring-mvc (Library): The Spring MVC library is going to be removed in version 6.0.0 of openapi-generator. Users should upgrade to the Spring Boot based library. Since the library is based on dependencies which are declared EOL (spring-framework 4.x) and we have no plans to move it forward, it has to be removed for security and maintenance reasons.

Users who need to support Swagger1 Annotations (Annotate Model and Api using the Swagger Annotations 1.x library) could do so independently of Springfox using annotationLibrary=swagger1.

Shown in the command line help
Added to the generated documentation (spring.md)
Added to the generated README.md
Logged at WARNING level on each invocation.

PR checklist

[x ] Read the contribution guidelines.
[ x] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
[ x] Run the following to build the project and update samples:
```
./mvnw clean package 
./bin/generate-samples.sh
./bin/utils/export_docs_generators.sh
```
Commit all changed files.
This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
These must match the expectations made by your contribution.
You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
For Windows users, please run the script in Git BASH.
[ x] File the PR against the correct branch: master (5.3.0), 6.0.x
[ x] If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

- Bring homeController.mustache up-to-date - Main class is now OpenApiGeneratorApplication - Introduce SpringBootTest.mustache - Remove option swaggerDocketConfig/openapiDocketConfig in favor of documentationProvider.

Fix spring-mvc builds

…flux-ui

cachescrubber · 2022-02-06T12:19:05Z

re-open to trigger CI

cachescrubber · 2022-02-06T12:48:23Z

There is a new spring-boot sample, spring-boot-source.yaml. It has should be registered as a new CI build.

cachescrubber · 2022-02-06T13:44:48Z

@wing328 , @welshm FYI

welshm

Just a minor comment - I think that interface only is not exclusive to swagger-ui

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

# Conflicts: # modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache # samples/openapi3/server/petstore/springboot-beanvalidation-no-nullable/src/main/java/org/openapitools/OpenAPI2SpringBoot.java # samples/server/petstore/java-camel/src/main/java/org/openapitools/OpenAPI2SpringBoot.java # samples/server/petstore/springboot-beanvalidation-no-nullable/.openapi-generator/FILES # samples/server/petstore/springboot-beanvalidation-no-nullable/src/main/java/org/openapitools/OpenAPI2SpringBoot.java # samples/server/petstore/springboot-spring-pageable-delegatePattern-without-j8/.openapi-generator/FILES # samples/server/petstore/springboot-spring-pageable-delegatePattern-without-j8/src/main/java/org/openapitools/OpenAPI2SpringBoot.java # samples/server/petstore/springboot-spring-pageable-without-j8/.openapi-generator/FILES # samples/server/petstore/springboot-spring-pageable-without-j8/src/main/java/org/openapitools/OpenAPI2SpringBoot.java

cachescrubber · 2022-02-10T05:39:38Z

@wing328 Could you remove the sprng-mvc samples from the CI configuration?

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

cachescrubber · 2022-02-10T08:24:05Z

Could you remove the sprng-mvc samples from the CI configuration?

I think I have done it with 87367b6. Please review.

…trap swagger-ui.

welshm

If someone requests the ability to generate the HTML with interfaces inky later, it's easy enough to reevaluate if that's a valid configuration we'd want to support.

Only other comment is about generating tests (I think there's a global generator property on whether or not tests should be output)

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

# Conflicts: # samples/server/petstore/spring-mvc-default-value/src/main/java/org/openapitools/api/TestHeadersApi.java # samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/FakeApi.java # samples/server/petstore/spring-mvc-j8-localdatetime/src/main/java/org/openapitools/api/FakeApi.java # samples/server/petstore/spring-mvc-no-nullable/src/main/java/org/openapitools/api/FakeApi.java # samples/server/petstore/spring-mvc-spring-pageable/src/main/java/org/openapitools/api/FakeApi.java # samples/server/petstore/spring-mvc/src/main/java/org/openapitools/api/FakeApi.java

…der' into feature/sourceDocumentationProvider

cachescrubber · 2022-02-12T08:19:19Z

Circle-CI failures are not caused by this pr IMO.

wing328 · 2022-02-12T09:25:15Z

CircleCI failures not related to this PR.

boardtc · 2023-01-20T16:54:54Z

fyi, Moving from 5.0.0 to 6.3.0-SNAPSHOT.a s suggested I tried spring-boot, but it does not recognise that library unless generatorName is set to spring

cachescrubber added 16 commits February 5, 2022 19:14

- Upgrade swagger-ui to 4.4.1

9c1d423

- Bring homeController.mustache up-to-date - Main class is now OpenApiGeneratorApplication - Introduce SpringBootTest.mustache - Remove option swaggerDocketConfig/openapiDocketConfig in favor of documentationProvider.

Generate Samples

97e847c

Restore generator-online classes

bbffdcd

Fix spring-mvc builds

Generate Samples

9c351da

Do not generate SpringFoxConfiguration.java when reactive ist set.

56a49a6

Fix generation of SpringFoxConfiguration

403852a

Generate Documentation

502587d

Reactive support: add dependency management for springdoc-openapi-web…

9e29c02

…flux-ui

Generate Samples

6b153a7

Change SpringBootApplication to OpenApiGeneratorApplication

6315747

Generate Samples

82b2f5d

Implement SwaggerUIFeatures in SpringCodegen

6ea78d1

Generate Samples

339cd54

Add useSwaggerUI: true to some test configs

730bdd1

Generate Samples

396ad6a

Update Documentation

9f63b42

cachescrubber closed this Feb 6, 2022

cachescrubber reopened this Feb 6, 2022

Update Documentation

c308f8d

cachescrubber added 2 commits February 6, 2022 14:21

Update README.mustache

b4f0482

Generate Samples

c33d8bf

welshm reviewed Feb 6, 2022

View reviewed changes

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java Show resolved Hide resolved

cachescrubber added 5 commits February 7, 2022 06:53

useSwaggerUI is true by default

d771121

Generate Samples

c6e3f5e

Update Documentation

f129eb2

Add deprecation warnings to cli opts; Log a deprecation warning

2d80a48

Update Documentation

f48db54

wing328 added Server: Java Server: Spring Enhancement: Feature labels Feb 8, 2022

wing328 added this to the 6.0.0 milestone Feb 8, 2022

cachescrubber added 3 commits February 10, 2022 06:16

Generate Samples

901cf29

Remove spring-mvc library

117edce

cachescrubber added 2 commits February 10, 2022 08:50

Merge branch 'master' into feature/sourceDocumentationProvider

87367b6

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

Remove spring-mvc from project and CI configs

33101fe

cachescrubber requested a review from jimschubert as a code owner February 10, 2022 08:13

cachescrubber added 2 commits February 11, 2022 08:56

Check whether the selected documentation provider requires us to boos…

d541c75

…trap swagger-ui.

Generate Samples

3257428

welshm approved these changes Feb 11, 2022

View reviewed changes

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java Show resolved Hide resolved

wing328 added the Decommission label Feb 12, 2022

wing328 changed the title ~~Implement Source DocumentationProvider~~ Implement Source DocumentationProvider, spring-mvc decomissino Feb 12, 2022

wing328 changed the title ~~Implement Source DocumentationProvider, spring-mvc decomissino~~ Implement Source DocumentationProvider, spring-mvc decommission Feb 12, 2022

cachescrubber added 5 commits February 12, 2022 08:49

Generate samples

82eee37

Merge remote-tracking branch 'origin/feature/sourceDocumentationProvi…

7ca877b

…der' into feature/sourceDocumentationProvider

Generate samples

41c5027

Generate samples

ed761ac

wing328 merged commit 0ed147e into OpenAPITools:master Feb 12, 2022

cachescrubber deleted the feature/sourceDocumentationProvider branch February 12, 2022 10:01

cachescrubber mentioned this pull request Feb 12, 2022

[Announcement] Deprecation Warnings for the Java/Spring Generator #11553

Open

sjoblomj mentioned this pull request Apr 20, 2022

[kotlin-spring] Adding DocumentationProvider and SwaggerUI #12184

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement Source DocumentationProvider, `spring-mvc` decommission #11531

Implement Source DocumentationProvider, `spring-mvc` decommission #11531

cachescrubber commented Feb 5, 2022 •

edited

Loading

cachescrubber commented Feb 6, 2022

cachescrubber commented Feb 6, 2022

cachescrubber commented Feb 6, 2022

welshm left a comment

cachescrubber commented Feb 10, 2022

cachescrubber commented Feb 10, 2022

welshm left a comment

cachescrubber commented Feb 12, 2022

wing328 commented Feb 12, 2022

boardtc commented Jan 20, 2023 •

edited

Loading

Implement Source DocumentationProvider, spring-mvc decommission #11531

Implement Source DocumentationProvider, spring-mvc decommission #11531

Conversation

cachescrubber commented Feb 5, 2022 • edited Loading

Finish the DocumentationProvider Story (#11258)

Changes

Deprecation Warnings

Removals

PR checklist

cachescrubber commented Feb 6, 2022

cachescrubber commented Feb 6, 2022

cachescrubber commented Feb 6, 2022

welshm left a comment

Choose a reason for hiding this comment

cachescrubber commented Feb 10, 2022

cachescrubber commented Feb 10, 2022

welshm left a comment

Choose a reason for hiding this comment

cachescrubber commented Feb 12, 2022

wing328 commented Feb 12, 2022

boardtc commented Jan 20, 2023 • edited Loading

Implement Source DocumentationProvider, `spring-mvc` decommission #11531

Implement Source DocumentationProvider, `spring-mvc` decommission #11531

cachescrubber commented Feb 5, 2022 •

edited

Loading

boardtc commented Jan 20, 2023 •

edited

Loading