Verwenden von Javadocs zum Generieren von Swagger-Dokument

Question

Ich möchte die Swagger-Dokumentation für eine bestehende Reihe von RESTful-APIs erstellen. Ich habe folgende Voraussetzung:

1. Generieren Swagger Doc offline (ich verwendete http://kongchen.github.io/swagger-maven-plugin/). Dieses Plugin hilft mir, die Swagger-Dokumentation während der Kompilierzeit zu generieren.
2. Lesen des vorhandenen Javadoc, damit sie in der Swagger-Dokumentation verwendet werden können.

Bisher das obige Plugin konnte ich Punkt erreichen, nein 1. So für eine bestehende REST-Methode:

/** 
* <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) { 
} 

konnte ich die Swagger Dokumentation erzeugen. Die Verwendung von @ApiOperation & @ApiResponses macht meine Dokumentation gut aussieht.

Meine Frage ist jedoch, kann ich die Javadocs verwenden, anstatt jeden Entwickler dazu zu bringen, @ApiOperation & @ApiResponses zu erstellen, damit es Zeit für mein Team spart?

Answer 1

Es scheint javadoc doclet zur Erzeugung von JSON Swagger Ressource-Eintrag zu sein: https://github.com/teamcarma/swagger-jaxrs-doclet

Answer 2

Sie können mit Enunciate, Prahlerei-ui von Javadoc erzeugen, die einen Swagger-Modul hat. Zuerst müssen Sie das Maven-Plugin zu Ihrer Pom-Datei hinzufügen. z.B.

<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> 

wo ‚enunciate.xml‘ Ihr Projekt spezifische Konfigurationen enthält und wie folgt aussieht:

<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> 

Dann mvn package laufen und es wird Swagger Dokumentationsdateien von Ihrem Javadoc generieren.