support for applying different context paths for sets of services

[ryangies]

Is there a way that each include within api-classes can specify its relativeContextPath?

Situation:

I have several services, each in their own Maven project and under the same groupId. These services as a whole comprise the application's interface. Because these interfaces call each other (using clients), Enunciate documents "too much" out of the box. I feel having each service exclude its siblings is cumbersome to maintain and violates the idea of isolation. Besides, I then have to wrap all the Enunciate docs in order to provide yet another main navigation to browse all of the interfaces.

Attempting this solution:

Create a dedicated project (pom.xml) with its own enunciate.xml for the sole purpose of documentation. This works great, except I cannot really tell which service is providing the interface. Thus circling back to the question at the top.

My ~ pom.xml:

<?xml version='1.0' encoding='utf-8'?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.company.app</groupId>
    <artifactId>app-apidocs</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>APIDocs</name>
    <properties>
        <maven.enunciate.plugin.version>2.11.1</maven.enunciate.plugin.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>com.company.app</groupId>
            <artifactId>first-service-interface</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>com.company.app</groupId>
            <artifactId>second-service-interface</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>com.webcohesion.enunciate</groupId>
                <artifactId>enunciate-maven-plugin</artifactId>
                <version>${maven.enunciate.plugin.version}</version>
                <configuration>
                    <docsDir>${project.build.directory}/docs</docsDir>
                    <exports>
                        <docs>apidocs.zip</docs>
                    </exports>
                    <excludes>
                        <exclude>org.springframework.**</exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <id>enunciate-docs</id>
                        <phase>package</phase>
                        <goals>
                            <goal>docs</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

My ~ enunciate.xml:

<?xml version="1.0" encoding="UTF-8"?>
<enunciate
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.10.0.xsd">
  <warnings>
    <disable name="source-files-not-found"/>
  </warnings>

  <api-classes>
    <include pattern="com.company.app.first.api.**"/>
    <include pattern="com.company.app.second.api.**"/>
  </api-classes>

  <modules>
    <docs includeExampleXml="false" includeApplicationPath="true"/>
    <c-xml-client disabled="true"/>
    <csharp-xml-client disabled="true"/>
    <java-json-client disabled="true"/>
    <java-xml-client disabled="true"/>
    <obj-c-xml-client disabled="true"/>
    <php-json-client disabled="true"/>
    <php-xml-client disabled="true"/>
    <ruby-json-client disabled="true"/>
  </modules>
</enunciate>

[stoicflame]

Well, there's the @com.webcohesion.enunciate.metadata.rs.ServiceContextRoot annotation, but you'd have to apply it to each resource, so that's a pain.

I'll track this as an enhancement request.

[stoicflame]

You can also use the @com.webcohesion.enunciate.metadata.rs.ResourceGroup annotation and apply some custom grouping. But, again, it's applied per-resource.

[ryangies]

Thank you. I will pursue the annotations in the meanwhile.