Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

support for applying different context paths for sets of services #868

Open
ryangies opened this issue May 24, 2018 · 3 comments
Open

support for applying different context paths for sets of services #868

ryangies opened this issue May 24, 2018 · 3 comments

Comments

@ryangies
Copy link

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 stoicflame added this to the 2.12.0 milestone May 24, 2018
@stoicflame
Copy link
Owner

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 stoicflame changed the title Dedicated APIDocs project support for applying different context paths for sets of services May 24, 2018
@stoicflame
Copy link
Owner

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
Copy link
Author

ryangies commented May 24, 2018

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

@stoicflame stoicflame removed this from the 2.12.0 milestone Aug 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants