Generate Rest API documentation with swagger Maven plugin

Generate Rest API documentation with swagger Maven plugin

Swagger Maven Plugin

This plugin enables your swagger-annotated project to generate Swagger Specs andcustomizable, templated static documentsduring the MAVEN build phase. Unlike Swagger-core, Swagger-maven-plugin does not actively serve the spec with the rest of the application; It generates the spec as a build artifact to being used in downstream Swagger tooling.

For more information, please visit the website:

Https://github.com/kongchen/swagger-maven-plugin

Exampleto add a plug-in to the POM:

 <build> <plugins> <plugin> <groupId>org.apache.maven.plugins<                     /groupid> <artifactId>maven-javadoc-plugin</artifactId> <configuration>                    <charset>UTF-8</charset> <docencoding>UTF-8</docencoding> <failOnError>false</failOnError> </configuration> </plugi n> <plugin> <groupId>com.github.kongchen</groupId> <artif Actid>swagger-maven-plugin</artifactid> <configuration> <apisources&gt                        ; <apiSource> <springmvc>false</springmvc> <locat           Ions>com.doctor.demo</locations> <schemes>http,https</schemes>                 
please go to https://github.com/swagger-maven-plugin/swagger-maven-example for the plugin template.download. 

Generate the API JSON file andswagger-ui display in:
1. MVN clean compile was executed under the project and Generated/swagger-ui/swagger.json was obtained.

2. Download the https://github.com/swagger-api/swagger-ui/tree/master/dist compiled version.

The 3.swagger.json is copied to the Dist directory. Then put the dist in the Tomcat WebApp directory. (You can copy the project directory from Dist to Tomcat).

4. Start Tomcat. The port is configured to 8888.

5. Open the Http://localhost:8888/dist/swagger-ui page.

6. Enter the address Http://localhost:8888/dist/swagger.json at the top of the Swagger-ui page to see the rest interface documentation.

7. (rest.png)



Appendix: Generated JSON file contents
{"Swagger": "2.0", "info": {"description": "This was a sample for Swagger-maven-plugin", "Version": "V1", "title": "Swagger Maven Plugin Sample", "Termsofservice": "Http://www.github.com/kongchen/swagger-maven-plugin", "    Contact ": {" name ":" Kong Chen "," url ":" http://kongch.com "," email ":" [email protected] "},  "License": {"name": "Apache 2.0", "url": "Http://www.apache.org/licenses/LICENSE-2.0.html"}}, "Host" : "Petstore.swagger.wordnik.com", "BasePath": "/api", "tags": [{"Name": "Hello Service"}], "Schemes": ["H TTP "," https "]," paths ": {"/hello/w ": {" post ": {" tags ": [" Hello Service "]," summary ":" T  Est Hello method "," description ":" Note "," OperationID ":" Hello "," consumes ": [" Application/json " ], "produces": ["Application/json"], "parameters": [{"In": "Body", "name": "Body" , "description" : "Welcomdto Object", "required": true, "schema": {"$ref": "#/definitions/welcomedto"            }}], "responses": {"$": {"description": "Successful Operation",  "Schema": {"$ref": "#/definitions/welcomeresponsedto"}}}}, "Definitions": {"welcomedto": {"type": "Object", "Properties": {"name": {"type": " String "}," age ": {" type ":" Integer "," Format ":" Int32 "}}}," Welc       Omeresponsedto ": {" type ":" Object "," Properties ": {" content ": {" type ":" String "} }    }  }}

Interface Description:
Package Com.doctor.demo.service;import Javax.ws.rs.consumes;import Javax.ws.rs.post;import javax.ws.rs.Path;import Javax.ws.rs.produces;import Javax.ws.rs.core.mediatype;import Com.doctor.demo.common.dto.welcomedto;import Com.doctor.demo.common.dto.welcomeresponsedto;import Io.swagger.annotations.api;import Io.swagger.annotations.apioperation;import Io.swagger.annotations.apiparam;import io.swagger.annotations.apiresponse;/** * @author sdcuike * * @time January 25, 2016 PM 11:07:44 */@Api (value = "Hello", tags = "h     Ello service ") @Path (" Hello ") public interface Hellorestservice {/** * Old interface mode (DTO) * * @param welcomdto * @return */@ApiOperation (value = "Test Hello method", notes = "note") @POST @Path ("W") @Consumes ({Media Type.application_json}) @Produces ({Mediatype.application_json}) @ApiResponse (message = "OK", Code = $) Welco Meresponsedto Hello (@ApiParam (value = "Welcomdto Object", required = True) Welcomedto welcomdto);}

Note: There are many more details that need to be modified. 
Generate Rest API documentation with swagger Maven plugin