利用Swagger Maven Plugin生成Rest API文档

利用Swagger Maven Plugin生成Rest API文档

Swagger Maven Plugin

This plugin enables your Swagger-annotated project to generate Swagger specs and customizable, templated static documents during 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 be used in downstream Swagger tooling.

预知详情，请到官网：

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

例子

在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>
            </plugin>

            <plugin>
                <groupId>com.github.kongchen</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <configuration>
                    <apiSources>
                        <apiSource>
                            <springmvc>false</springmvc>
                            <locations>com.doctor.demo</locations>
                            <schemes>http,https</schemes>
                            <host>petstore.swagger.wordnik.com</host>
                            <basePath>/api</basePath>
                            <info>
                                <title>Swagger Maven Plugin Sample</title>
                                <version>v1</version>
                                <description>This is a sample for swagger-maven-plugin</description>
                                <termsOfService>
                                    http://www.github.com/kongchen/swagger-maven-plugin
                                </termsOfService>
                                <contact>
                                    <email>kongchen@gmail.com</email>
                                    <name>Kong Chen</name>
                                    <url>http://kongch.com</url>
                                </contact>
                                <license>
                                    <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
                                    <name>Apache 2.0</name>
                                </license>
                            </info>
                            Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"
                            <templatePath>${basedir}/templates/strapdown.html.hbs</templatePath>
                            <outputPath>${basedir}/generated/document.html</outputPath>
                            <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
                        </apiSource>
                    </apiSources>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            
        </plugins>
    </build>

用到的插件模版请到https://github.com/swagger-maven-plugin/swagger-maven-example 

下载。

生成API json文件，并在swagger-ui中显示：

  1.在该项目下执行mvn clean compile，得到generated/swagger-ui/swagger.json.
 
 2.下载https://github.com/swagger-api/swagger-ui/tree/master/dist 编译后的版本。
 
 3.swagger.json拷贝到dist目录下。然后把dist放到tomcat webapp目录下。（可以把本项目目录下到dist之间copy到tomcat下）。
 
 4.启动tomcat。端口配置为8888。
 
 5.打开http://localhost:8888/dist/ swagger-ui页面。
 
 6.在swagger-ui页面顶端输入地址http://localhost:8888/dist/swagger.json，即可看到rest接口文档。
 
 7.截图（rest.png)

附录：生成的json文件内容

 

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is 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" : "kongchen@gmail.com"
    },
    "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" : [ "http", "https" ],
  "paths" : {
    "/hello/w" : {
      "post" : {
        "tags" : [ "hello service" ],
        "summary" : "test 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" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/WelcomeResponseDto"
            }
          }
        }
      }
    }
  },
  "definitions" : {
    "WelcomeDto" : {
      "type" : "object",
      "properties" : {
        "name" : {
          "type" : "string"
        },
        "age" : {
          "type" : "integer",
          "format" : "int32"
        }
      }
    },
    "WelcomeResponseDto" : {
      "type" : "object",
      "properties" : {
        "content" : {
          "type" : "string"
        }
      }
    }
  }
}

接口描述：

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 2016年1月25日 下午11:07:44
 */
@Api(value = "hello", tags = "hello service")
@Path("hello")
public interface HelloRestService {
    /**
     * 老接口方式（DTO)
     * 
     * @param welcomDto
     * @return
     */
    @ApiOperation(value = "test hello method", notes = "note")

    @POST
    @Path("w")
    @Consumes({ MediaType.APPLICATION_JSON })
    @Produces({ MediaType.APPLICATION_JSON })
    @ApiResponse(message = "ok", code = 200)
    WelcomeResponseDto hello(@ApiParam(value = "welcomDto object", required = true) WelcomeDto welcomDto);

}

注：还有很多细节需要修改。