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>