软件世界网 购物 网址 三丰软件 | 小说 美女秀 图库大全 游戏 笑话 | 下载 开发知识库 新闻 开发 图片素材
多播视频美女直播
↓电视,电影,美女直播,迅雷资源↓
TxT小说阅读器
↓语音阅读,小说下载,古典文学↓
一键清除垃圾
↓轻轻一点,清除系统垃圾↓
图片批量下载器
↓批量下载图片,美女图库↓
移动开发 架构设计 编程语言 Web前端 互联网
开发杂谈 系统运维 研发管理 数据库 云计算 Android开发资料
  软件世界网 -> 研发管理 -> 利用SwaggerMavenPlugin生成RestAPI文档 -> 正文阅读

[研发管理]利用SwaggerMavenPlugin生成RestAPI文档

利用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)

[img]http://img.blog.csdn.net/20160306234150965?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center

附录:生成的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);

}

注:还有很多细节需要修改。
......显示全文...
    点击查看全文


上一篇文章      下一篇文章      查看所有文章
2016-03-07 12:43:12  
研发管理 最新文章
拉格朗日乘数
maven之可视化项目依赖(Visualizingdepend
mac效率工具
Atitit.css规范bem项目中CSS的组织和管理
git入门
Asimplemodelfordescribingbasicsourcesofp
Linux进程管理浅析
我的openwrt学习笔记(十九):linux便捷开
2、微控制器选择
Git使用手册:为Git仓库创建Submodule
360图书馆 软件开发资料 文字转语音 购物精选 软件下载 美食菜谱 新闻资讯 电影视频 小游戏 Chinese Culture 股票 租车
生肖星座 三丰软件 视频 开发 短信 中国文化 网文精选 搜图网 美图 阅读网 多播 租车 短信 看图 日历 万年历 2018年1日历
2018-1-17 14:48:33
多播视频美女直播
↓电视,电影,美女直播,迅雷资源↓
TxT小说阅读器
↓语音阅读,小说下载,古典文学↓
一键清除垃圾
↓轻轻一点,清除系统垃圾↓
图片批量下载器
↓批量下载图片,美女图库↓
  网站联系: qq:121756557 email:121756557@qq.com  软件世界网 --