Używanie dokumentacji Javadocs do generowania dokumentu Swagger

Question

Chcę utworzyć dokumentację Swagger dla istniejącego zestawu interfejsów API RESTful. Mam następujący warunek:

1. Generowanie Swagger Doc offline (użyłem http://kongchen.github.io/swagger-maven-plugin/). Ta wtyczka pomaga mi generować dokumentację Swagger podczas kompilacji.
2. Odczytywanie istniejącej dokumentacji Javadoc, aby można było jej używać w dokumentacji Swagger.

tej pory przy użyciu powyższej wtyczki udało mi się osiągnąć punkt nr 1. Tak dla istniejącej metody rekreacyjne:

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

byłem w stanie wygenerować dokumentację Swagger. Korzystanie z @ApiOperation & @ ApiResponses sprawia, że ​​moja dokumentacja wygląda świetnie.

Jednak moje pytanie brzmi: czy mogę użyć Javadocs zamiast tworzyć każdego dewelopera do tworzenia @ApiOperation & @ApiResponses, aby oszczędzić czas dla mojego zespołu?

Answer 1

Wydaje się javadoc doclet generowania JSON Swagger listę zasobów: https://github.com/teamcarma/swagger-jaxrs-doclet

Answer 2

Można wygenerować Swagger-ui z Javadoc za pomocą Enunciate, który posiada moduł Swagger. Najpierw musisz dodać wtyczkę maven do pliku pom; na przykład

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

gdzie „enunciate.xml” zawiera specyficzne konfiguracje projektu i wygląda następująco:

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

Następnie uruchom mvn package i będzie generować pliki dokumentacji Swagger z Javadoc.