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