一 简介

Swagger是一个开源项目,用于描述和生成RestAPi的文档。可以帮助开发人员快速了解web服务的功能。

二  接入Swagger流程

1.在所在Module的pom.xml中,添加Swagger annotation 依赖

<dependency>
    <groupId>com.wordnik</groupId>
    <artifactId>swagger-annotations</artifactId>
    <scope>compile</scope>
    <version>1.5.1-M2</version>
</dependency>

2.在classpath:/templates/目录,添加swagger maven plugin需要的模板templates.zip

3.在Controller所在Module的pom.xml文件中配置swagger maven plugin

<plugin>
   <groupId>com.swagger.test</groupId>
   <artifactId>swagger-maven-plugin</artifactId>
   <version>3.0.5</version>
   <configuration>
      <enable>${doc-enable}</enable> <!--注意这里 -->
      <apiSources>
         <apiSource>
            <springmvc>true</springmvc> <!--是否spring mvc项目,我们的项目都填是  -->
            <locations>com.swagger.web</locations><!--Controller所在包  -->
            <schemes>http</schemes><!--协议  -->
            <host></host><!-- 服务器地址,空值表示跟文档是同一台机器(域名) -->
            <basePath>/test</basePath><!-- api url 前缀  -->
            <info>
               <title>test API</title><!-- Api 标题啊 -->
               <version>v1</version><!-- Api版本 -->
               <description>test API的详细描述</description><!-- Api的详细描述 -->
               <termsOfService>
                  http://www.test.com
               </termsOfService>
               <contact>
                  <email>123@qq.com</email><!-- 联系人邮件  -->
                  <name>yourname</name><!-- 联系人姓名 -->
               </contact>
            </info>
            <templatePath>classpath:/templates/strapdown.html.hbs</templatePath><!-- 文档模板 -->
            <outputPath>${basedir}/src/main/webapp/doc/document.html</outputPath><!-- 文档输出路径,设置在和SwaggerUI同一目录 -->
            <swaggerDirectory>${basedir}/src/main/webapp/doc/</swaggerDirectory><!-- Swagger.json输出路径,设置在和SwaggerUI同一目录 -->
         </apiSource>
      </apiSources>
   </configuration>
   <executions>
      <execution>
         <phase>compile</phase>
         <goals>
            <goal>generate</goal>
         </goals>
      </execution>
   </executions>
</plugin>

其中,enable如果设置为true的话,就会一直生成文档,如果想分环境设置的话,可以在profile里配置doc-enable变量属性实现

<profiles>
    <profile>
        <id>local</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <conf-dir>local</conf-dir>
            <doc-enable>true</doc-enable>
        </properties>
    </profile>
</profiles>

4.将Swagger UI添加到项目的web目录下swagger_ui.zip,修改index.html文件第29行

url = "/jingquadmin/doc/swagger.json"  TO  url = "/yoururl/doc/swagger.json"

(另,附件中的document.html和swagger.json是插件swagger maven plugin自动生成的,添加与否均可)

(添加Swagger UI,主要是为了API的可视化)

5.在Controller上添加API annotation,在Controller接口上添加Swagger annotation

6.maven编译项目,然后启动项目或plus发布项目,链接如下:

http://host/basepath/doc/index.html   自动测试平台

http://host/basepath/doc/document.html   API文档

三  Swagger常用注解介绍

 
 
 
annotation
说明
属性介绍
Api 加在Controller类上,将Controller标记为Swagger资源

value - 名称

description - 描述

ApiOperation 加在Controller方法上,表明这个方法是一个rest接口,一个@Api下可有多个@ApiOperation(一个Controller文件可有多个接口)

value - 接口名称

notes - 详细描述

response - 返回类

ApiImplicitParams/ApiImplicitParam/ApiParam 加在Controller方法上,表明这里需要隐藏的参数

name - 参数名

value - 参数描述

defaultValue - 默认值

required - 是否必需

dataType - 数据类型

ApiModel 加在Model类上,用来描述封装的参数对象和返回的参数对象 description - 描述
ApiModelProperty 加在Model类的属性上,描述参数的对象属性

value - 属性描述

完整Annotation详见http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html

 

其他:

SpringMVC项目也可以通过接入Springfox来自动生成API文档,Springfox的前身是swagger-SpringMVC,一个开源的API doc框架。

注意:

在Controller文件中定义接口时,@RequestMapping注解中的method属性是必须要设置的,否则Swagger插件不会生成对应接口信息;

@RequestMapping(value = "/v2/group", method = RequestMethod.GET)

*内部人员(绿山墙注)

Swagger接入的更多相关文章

  1. ASP.NET Core Swagger接入使用IdentityServer4 的 WebApi

    写在前面 是这样的,我们现在接口使用了Ocelot做网关,Ocelot里面集成了基于IdentityServer4开发的授权中心用于对Api资源的保护.问题来了,我们的Api用了SwaggerUI做接 ...

  2. 接口文档神器Swagger(下篇)

    本文来自网易云社区 作者:李哲 二.Swagger-springmvc原理解析 上面介绍了如何将springmvc和springboot与swagger结合,通过简单配置生成接口文档,以及介绍了swa ...

  3. Asp.Net Core SwaggerUI 接入

    Asp.Net Core SwaggerUI 接入 简单了解 swagger的目的简单来说就是,不用为每个接口手动写接口文档,因为它是根据接口自动生成的,接口更改时文档也同步更新,减少了手动更新的麻烦 ...

  4. swagger在线api文档搭建指南,用于线上合适么?

    在上一篇文章中,我们讲解了什么是 api,什么是 sdk: https://www.cnblogs.com/tanshaoshenghao/p/16217608.html 今天将来到我们万丈高楼平地起 ...

  5. [Abp vNext 入坑分享] - 6.完整接入swagger

    前言 由于最近一直在修改一下排版,同时找了非技术的朋友帮忙看一下排版的问题,现在已经基本上确定了排版和样式了.更新可以恢复正常了. 作为一个写前端代码基本只写js不写css的开发,搞排版真的头疼..各 ...

  6. Asp.Net Core WebApi中接入Swagger组件(初级)

    开发WebApi时通常需要为调用我们Api的客户端提供说明文档.Swagger便是为此而存在的,能够提供在线调用.调试的功能和API文档界面. 环境介绍:Asp.Net Core WebApi + S ...

  7. WebApi接入Swagger

    1.新建webApi项目 2.nuget引入 swagger 3.在项目属性里配置输出 xml文件 4.打开SwaggerConfig.cs编辑 protected static string Get ...

  8. spring接入swagger后单元测试报错

    2017-05-16 11:58:05.276 INFO 11268 --- [ main] s.c.a.AnnotationConfigApplicationContext : Refreshing ...

  9. net core体系-API-Restful+Swagger搭建API

    本篇主要简单介绍下.net core下搭建WebApi 项目结构 项目结构其实不用多说,基本上大同小异. Controller:对外暴露的契约 Business/IBussiness:业务逻辑层实现及 ...

随机推荐

  1. [数据库事务与锁]详解八:底理解数据库事务乐观锁的一种实现方式——CAS

    注明: 本文转载自http://www.hollischuang.com/archives/1537 在深入理解乐观锁与悲观锁一文中我们介绍过锁.本文在这篇文章的基础上,深入分析一下乐观锁的实现机制, ...

  2. atitit.vod search doc.doc 点播系统搜索功能设计文档

    atitit.vod search doc.doc 点播系统搜索功能设计文档 按键的enter事件1 Left rig事件1 Up down事件2 key_events.key_search = fu ...

  3. Python - 动手写个ORM

    Python - 动手写个ORM 任务: 模拟简单的ORM - Object Relational Mapping 为model添加create方法 代码很简单,直接上 字段类型类 class Fie ...

  4. CCNA网络工程师学习进程(3)常规网络设计模型与基本的网络协议

        本节介绍分层的网络设计模型与基本的网络协议,包括ARP协议,ICMP协议和IP协议.     (1)三层网络架构: 一个好的园区网设计应该是一个分层的设计.一般分为接入层.汇聚层(分布层).核 ...

  5. struts之动态方法调用使用通配符

    一.DMI动态方法调用的其中一种改变form表单中action属性的方式已经讲过了.还有两种,一种是改变struts.xml配置文件中action标签中的method属性,来指定执行不同的方法处理不同 ...

  6. iOS开发中 workspace 与 static lib 工程的联合使用

    在iOS开发中,其实workspace的使用没有完全发挥出来,最近做了一些研究,也想把之前写过的代码整理下,因为iOS里面的布局方式,交互方式也就那么几种.所以,整理好了之后,更能快捷开发,而且能够形 ...

  7. 分享一个 C# Winfrom 下的 OutlookBar 控件的使用

    最近在上网的时候,发现了这个C# 下的 OutlookBar 控件,看了一下感觉还真不错,特此记录一下. using System; using System.Drawing; using Syste ...

  8. 有关try..catch..finally处理异常的总结

    //看一下下面的程序,你能正确的写出不同的testEx2()方法时,程序的最终打印出来的数据吗....先不要看下面的答案 public class ExceptionTest { public Exc ...

  9. java中异常注意问题(发生在多态是的异常问题)

    /* 异常的注意事项: 1,子类在覆盖父类方法时,父类的方法如果抛出了异常,那么子类的方法只能抛出父类的异常或者该异常的子类. 2,如果父类抛出多个异常,那么子类只能抛出父类异常的子集. 简单说:子类 ...

  10. 《BI那点儿事》Microsoft 决策树算法——找出三国武将特性分布,献给广大的三国爱好者们

    根据游戏<三国志11>武将数据,利用决策树分析,找出三国武将特性分布.其中变量包括统率.武力.智力.政治.魅力.身分.变量说明:统率:武将带兵出征时的部队防御力.统帅越高受到普通攻击与兵法 ...