迁移至io.swagger.core.v3插件后，能否实现descriptionFile功能？

Great question! Let me break this down clearly for you:

The io.swagger.core.v3:swagger-maven-plugin (the official OpenAPI 3.x plugin) does not have a direct equivalent to the <descriptionFile> configuration from the old com.github.kongchen:swagger-maven-plugin. That feature was specific to the third-party Kongchen plugin, and the official plugin focuses on a code-first, annotation-driven workflow.

But don’t worry—there are solid workarounds to achieve the same goal of pulling external description content into your generated OpenAPI spec:

Workaround 1: Annotation-based Configuration with Maven Filtering #

You can use OpenAPI 3 annotations in your code to define API metadata, and leverage Maven resource filtering to inject content from your src/doc/Swagger-Description.md file:

1. Add the @OpenAPIDefinition and @Info annotations to a configuration class in your code, with a placeholder for the description:

   @OpenAPIDefinition(
       info = @Info(
           title = "Your API Title",
           version = "1.0.0",
           description = "${api.description}"
       )
   )
   public class ApiMetadataConfig {}
   

2. In your pom.xml, enable filtering for the class containing the annotation, and define a property that reads your markdown file:

   <properties>
       <api.description>${file:src/doc/Swagger-Description.md}</api.description>
   </properties>
   
   <build>
       <resources>
           <resource>
               <directory>src/main/java</directory>
               <filtering>true</filtering>
               <includes>
                   <include>**/ApiMetadataConfig.java</include>
               </includes>
           </resource>
       </resources>
   </build>
   

3. Run the swagger-maven-plugin as usual—it will pick up the injected markdown content during code processing.

Workaround 2: Post-Generation Merging with a Maven Plugin #

If you prefer to keep description content completely separate from code, generate the base OpenAPI spec first, then merge the markdown into the final file using a secondary plugin:

1. Configure the swagger-maven-plugin to generate an initial spec (e.g., to target/openapi-base.yaml).
2. Add a plugin like org.codehaus.mojo:yaml-maven-plugin to update the info.description field with your markdown content:

   <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>yaml-maven-plugin</artifactId>
       <version>1.5</version>
       <executions>
           <execution>
               <id>merge-description</id>
               <goals>
                   <goal>update</goal>
               </goals>
               <configuration>
                   <inputFile>target/openapi-base.yaml</inputFile>
                   <outputFile>target/openapi.yaml</outputFile>
                   <updates>
                       <update>
                           <path>/info/description</path>
                           <value>${file:src/doc/Swagger-Description.md}</value>
                       </update>
                   </updates>
               </configuration>
           </execution>
       </executions>
   </plugin>
   

3. Run your Maven build—the final target/openapi.yaml will include your full markdown description.

Both approaches work reliably: the first integrates tightly with the code-first workflow, while the second keeps metadata fully decoupled from your application code.

内容的提问来源于stack exchange，提问作者Marius