Merge "Bug-915: Adding static document generation. Currently the API Explorer can...
[controller.git] / opendaylight / md-sal / sal-rest-docgen / src / main / resources / README.txt
1 This component offers Swagger documentation of the RestConf APIs.
2
3 This Swagger documentation can be accessed in two ways:
4 I. Running server
5 Open a browser and go to http://<host>:8181/apidoc/explorer/index.html
6
7 II. Static documentation generation
8 By adding a reference to the StaticDocGenerator class in any pom.xml,
9 static documentation will be generated.  This static documentation will
10 document all the RestConf APIs for the YANG files in that artifact and
11 all the YANG files in that artifact's dependencies.
12
13 In order to generate static documentation for all resources,
14 this should be placed in a downstream project.
15
16 Below is what you would add to the <plugins> section under <build>.
17       <plugin>
18         <groupId>org.apache.maven.plugins</groupId>
19         <artifactId>maven-dependency-plugin</artifactId>
20         <version>2.8</version>
21         <executions>
22           <execution>
23             <id>unpack-static-documentation</id>
24             <goals>
25               <goal>unpack-dependencies</goal>
26             </goals>
27             <phase>generate-resources</phase>
28             <configuration>
29               <outputDirectory>${project.build.directory}/generated-resources/swagger-api-documentation</outputDirectory>
30               <includeArtifactIds>sal-rest-docgen</includeArtifactIds>
31               <includes>**/explorer/css/**/*, **/explorer/images/**/*, **/explorer/lib/**/*, **/explorer/static/**/*,</includes>
32               <excludeTransitive>true</excludeTransitive>
33               <ignorePermissions>false</ignorePermissions>
34             </configuration>
35           </execution>
36         </executions>
37       </plugin>
38       <plugin>
39         <groupId>org.opendaylight.yangtools</groupId>
40         <artifactId>yang-maven-plugin</artifactId>
41         <version>${yangtools.version}</version>
42         <dependencies>
43           <dependency>
44             <groupId>org.opendaylight.yangtools</groupId>
45             <artifactId>maven-sal-api-gen-plugin</artifactId>
46             <version>${yangtools.version}</version>
47             <type>jar</type>
48           </dependency>
49           <dependency>
50             <groupId>org.opendaylight.yangtools</groupId>
51             <artifactId>yang-binding</artifactId>
52             <version>${yangtools.version}</version>
53             <type>jar</type>
54           </dependency>
55           <dependency>
56             <groupId>org.opendaylight.controller</groupId>
57             <artifactId>sal-rest-docgen</artifactId>
58             <version>${mdsal.version}</version>
59             <type>jar</type>
60           </dependency>
61         </dependencies>
62         <executions>
63           <execution>
64             <goals>
65               <goal>generate-sources</goal>
66             </goals>
67             <configuration>
68               <yangFilesRootDir>src</yangFilesRootDir>
69               <codeGenerators>
70                 <generator>
71                   <codeGeneratorClass>org.opendaylight.controller.sal.rest.doc.impl.StaticDocGenerator</codeGeneratorClass>
72                   <outputBaseDir>${project.build.directory}/generated-resources/swagger-api-documentation/explorer/static</outputBaseDir>
73                 </generator>
74               </codeGenerators>
75               <inspectDependencies>true</inspectDependencies>
76             </configuration>
77           </execution>
78         </executions>
79       </plugin>

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.