软件世界网 购物 网址 三丰软件 | 小说 美女秀 图库大全 游戏 笑话 | 下载 开发知识库 新闻 开发 图片素材
多播视频美女直播
↓电视,电影,美女直播,迅雷资源↓
TxT小说阅读器
↓语音阅读,小说下载,古典文学↓
一键清除垃圾
↓轻轻一点,清除系统垃圾↓
图片批量下载器
↓批量下载图片,美女图库↓
移动开发 架构设计 编程语言 Web前端 互联网
开发杂谈 系统运维 研发管理 数据库 云计算 Android开发资料
  软件世界网 -> 研发管理 -> 利用SwaggerMavenPlugin生成RestAPI文档 -> 正文阅读
研发管理 最新文章
拉格朗日乘数
maven之可视化项目依赖(Visualizingdepend
mac效率工具
Atitit.css规范bem项目中CSS的组织和管理
git入门
Asimplemodelfordescribingbasicsourcesofp
Linux进程管理浅析
我的openwrt学习笔记(十九):linux便捷开
2、微控制器选择
Git使用手册:为Git仓库创建Submodule

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

  2016-03-07 12:43:14

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

}

注:还有很多细节需要修改。
上一篇文章      下一篇文章      查看所有文章
2016-03-07 12:43:12  
360图书馆 论文大全 母婴/育儿 软件开发资料 网页快照 文字转语音 购物精选 软件 美食菜谱 新闻中心 电影下载 小游戏 Chinese Culture
生肖星座解梦 三沣玩客 拍拍 视频 开发 Android开发 站长 古典小说 网文精选 搜图网 天下美图 中国文化英文 多播视频 装修知识库
2017-1-18 20:01:33
多播视频美女直播
↓电视,电影,美女直播,迅雷资源↓
TxT小说阅读器
↓语音阅读,小说下载,古典文学↓
一键清除垃圾
↓轻轻一点,清除系统垃圾↓
图片批量下载器
↓批量下载图片,美女图库↓
  网站联系: qq:121756557 email:121756557@qq.com  软件世界网 --