web-dev-qa-db-fra.com

Utiliser Javadocs pour générer un document Swagger

Je souhaite créer la documentation Swagger pour un ensemble existant d’API RESTful. J'ai l'exigence suivante:

  1. Générez Swagger Doc hors ligne (j'ai utilisé http://kongchen.github.io/swagger-maven-plugin/ ). Ce plugin m'aide à générer la documentation Swagger pendant la compilation.
  2. Lecture de la Javadoc existante afin qu'elle puisse être utilisée dans la documentation Swagger.

Jusqu'ici, en utilisant le plugin ci-dessus, j'ai pu atteindre le point 1. Donc, pour une méthode existante REST:

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

J'ai pu générer la documentation Swagger. L'utilisation de @ApiOperation & @ApiResponses rend ma documentation très belle.

Cependant, ma question est la suivante: puis-je utiliser les Javadocs au lieu de faire en sorte que chaque développeur crée @ApiOperation & @ApiResponses afin de gagner du temps pour mon équipe?

javamavenswaggerswagger-maven-plugin
14
Raj

Vous pouvez générer swagger-ui à partir de Javadoc en utilisant Enunciate , qui contient un module Swagger. Tout d’abord, vous devez ajouter le plugin maven à votre fichier pom; par exemple.

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

où 'enunciate.xml' contient les configurations spécifiques à votre projet et se présente comme suit:

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

Ensuite, lancez mvn compile et il générera des fichiers de documentation Swagger à partir de votre Javadoc.

12
Egemen

Il semble exister un doclet javadoc pour générer la liste de ressources JSON Swagger: https://github.com/teamcarma/swagger-jaxrs-doclet

0
dsavickas