Swagger接入

一 简介

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)

*内部人员（绿山墙注）