Utilizzo di Javadocs per generare il documento Swagger

Question

Desidero creare la documentazione di Swagger per un set esistente di API RESTful. Ho il seguente requisito:

1. Generare offline Swagger Doc (ho utilizzato http://kongchen.github.io/swagger-maven-plugin/). Questo plugin mi aiuta a generare la documentazione di Swagger durante la compilazione.
2. Leggere il Javadoc esistente in modo che possano essere utilizzati nella documentazione di Swagger.

Finora utilizzando il plugin di cui sopra sono stato in grado di raggiungere il punto numero 1. Così, per un metodo REST esistente:

/** 
* <p> 
* Gets the {@link DisplayPreferenceModel} with the name as provided in the parameter. The preference with the given name defined at the tenant or master level is returned. 
* This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required. 
* </p> 
* @param preferenceName 
*   - The name of the preference. 
* @return {@link DisplayPreferenceModel} 
*/ 
@RequestMapping(method = RequestMethod.GET, value = "/preferences/{preferenceName}") 
@ApiOperation(value = "This API gives us the preference if it is eligible for unauthorized access If it is not eligible it throws an Exception saying Authorization required", 
         notes = "No Notes please", response = DisplayPreferenceModel.class) 
@ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Invalid preferenceName supplied"), 
         @ApiResponse(code = 404, message = "Display Preference Not Found") 
         } 
      ) 
public DisplayPreferenceModel getDisplayPreference(@PathVariable("preferenceName") final String preferenceName) { 
} 

sono stato in grado di generare la documentazione Swagger. L'utilizzo di @ApiOperation & @ApiResponses rende la documentazione eccellente.

Tuttavia, la mia domanda è possibile utilizzare Javadoc invece di fare in modo che ogni sviluppatore crei @ApiOperation & @ApiResponses in modo da risparmiare tempo per la mia squadra?

Answer 1

Sembra che ci sia javadoc doclet per la generazione di JSON Swagger lista risorsa: https://github.com/teamcarma/swagger-jaxrs-doclet

Answer 2

È possibile generare spavalderia-ui da Javadoc utilizzando Enunciate, che ha un modulo di Swagger. In primo luogo, è necessario aggiungere il plugin Maven al tuo file pom; per esempio.

<plugin> 
     <groupId>com.webcohesion.enunciate</groupId> 
     <artifactId>enunciate-maven-plugin</artifactId> 
     <version>${enunciate.version}</version> 
     <executions> 
      <execution> 
        <goals> 
        <goal>docs</goal> 
        </goals> 
        <configuration> 
        <configFile>enunciate.xml</configFile> 
        <docsDir>${project.build.directory}</docsDir> 
        </configuration> 
      </execution> 
     </executions> 
</plugin> 

dove 'enunciate.xml' contiene le configurazioni specifiche di progetto e si presenta così:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.0.0-M.3.xsd"> 

    <application root="/rest" /> 

</enunciate> 

Quindi eseguire mvn package e genererà file di documentazione Swagger dal Javadoc.