Spring MVC - RAML Spec Synchroniser简介

雨点打透心脏的1/2处 2022-06-12 01:45 204阅读 0赞

1. Spring MVC - RAML Spec Synchroniser是一个工具，用以在Spring MVC应用和RAML文件定义之间进行同步。即Spring MVC应用的变化，可以通过该工具同步体现在RAML文件的定义中；反之亦然。

该工具包含如下3个独立的组件：

*  springmvc-raml-plugin
 *  springmvc-raml-parser（忽略），解析Spring Annotations以生产RAML文件
 *  springmvc-raml-annotations（忽略），定制Annotations

我们关注其中的springmvc-raml-plugin插件。

2. springmvc-raml-plugin是一个Maven插件，用以从RAML文件生成Spring框架的服务器端和客户端代码，或者反之。

1)从Spring代码实现生成RAML文件

pom.xml文件配置如下：

<plugin>
      <groupId>com.phoenixnap.oss</groupId>
      <artifactId>springmvc-raml-plugin</artifactId>
      <version>0.8.6</version>
      <configuration>
        <outputRamlFilePath>/src/main/resources/public/raml/api.raml</outputRamlFilePath>
    	<javaDocPath>D:/</javaDocPath>
        <restBasePath>/</restBasePath>
        <version>0.0.1</version>
        <includeGlobalMediaType>false</includeGlobalMediaType>
    	<restrictOnMediaType>false</restrictOnMediaType>
    	<ignoredList>
    	   <param>com.package.to.ignore</param>
    	   <param>com.specificClass.to.ignore.ClassName</param>
    	</ignoredList>
    	<dependencyPackagesList>
    	   <param>com.package.in.dependency.jar.to.include</param>
    	</dependencyPackagesList>
      </configuration>
      <executions>
        <execution>
          <id>generate-springmvc-api-docs</id>
          <phase>compile</phase>
          <goals>
            <goal>generate-springmvc-api-docs</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

执行mvn clean install即可。

2)从RAML文件生成Spring代码实现

pom.xml文件配置如下：

<plugin>
      <groupId>com.phoenixnap.oss</groupId>
      <artifactId>springmvc-raml-plugin</artifactId>
      <version>0.8.6</version>
      <configuration>
        <ramlPath>{path.to.raml.file}</ramlPath>
    	<schemaLocation>{path.to.schema.directory||schema.absolute.url}</schemaLocation>
    	<outputRelativePath>/src/generated</outputRelativePath>
        <addTimestampFolder>false</addTimestampFolder>
        <basePackage>com.gen.wow</basePackage>
        <baseUri>/api</baseUri>
        <generateUnreferencedSchemas>true</generateUnreferencedSchemas>
    	<generationConfig>
    		<includeAdditionalProperties>false</includeAdditionalProperties>
    		...
    	</generationConfig>
    	<seperateMethodsByContentType>false</seperateMethodsByContentType>
    	<rule>com.phoenixnap.oss.ramlapisync.generation.rules.Spring4ControllerStubRule</rule>
    	<ruleConfiguration>			
    	</ruleConfiguration>
      </configuration>
      <executions>
        <execution>
          <id>generate-springmvc-endpoints</id>
          <phase>compile</phase>
          <goals>
            <goal>generate-springmvc-endpoints</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

执行mvn clean install即可。

3)检查RAML文件，验证生成的Spring代码实现

pom.xml文件配置如下：

<plugin>
      <groupId>com.phoenixnap.oss</groupId>
      <artifactId>springmvc-raml-plugin</artifactId>
      <version>0.8.6</version>
      <configuration>
        <ramlToVerifyPath>/src/main/resources/public/raml/api.raml</ramlToVerifyPath>
    	<javaDocPath>D:/</javaDocPath>
        <performStyleChecks>true</performStyleChecks>
    	<checkRamlAgainstImplementation>true</checkRamlAgainstImplementation>
    	<checkForResourceExistence>true</checkForResourceExistence>
    	<checkForActionExistence>true</checkForActionExistence>
    	<checkForQueryParameterExistence>true</checkForQueryParameterExistence>
    	<checkForPluralisedResourceNames>true</checkForPluralisedResourceNames>
    	<checkForSpecialCharactersInResourceNames>true</checkForSpecialCharactersInResourceNames>
    	<checkForDefinitionOf40xResponseInSecuredResource>true</checkForDefinitionOf40xResponseInSecuredResource>
    	<checkForSchemaInSuccessfulResponseBody>true</checkForSchemaInSuccessfulResponseBody>
    	<checkForSchemaInRequestBody>true</checkForSchemaInRequestBody>
    	<checkForDefinitionOf404ResponseInGetRequest>true</checkForDefinitionOf404ResponseInGetRequest>
    	<checkForResponseBodySchema>true</checkForResponseBodySchema>
    	<breakBuildOnWarnings>false</breakBuildOnWarnings>
        <logWarnings>true</logWarnings>
        <logErrors>true</logErrors>
    	<ignoredList>
    	   <param>com.package.to.ignore</param>
    	   <param>com.specificClass.to.ignore.ClassName</param>
    	</ignoredList>
    	<dependencyPackagesList>
    	   <param>com.package.in.dependency.jar.to.include</param>
    	</dependencyPackagesList>
      </configuration>
      <executions>
        <execution>
          <id>generate-springmvc-api-docs</id>
          <phase>compile</phase>
          <goals>
            <goal>verify-springmvc-api-docs</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

执行mvn clean install即可。

参考链接：

https://github.com/phoenixnap/springmvc-raml-plugin