Generate Rest API documentation with swagger Maven plugin

Source: Internet
Author: User

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

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.