Swagger框架学习分享

转至元数据结尾

• Created and last modified by 刘新宇 大约1分钟以前

转至元数据起始

1.1.项目简介

Swagger项目是由Dilip Krishnan和Adrian Kelly等人维护开发的一个为Spring Web MVC 项目提供方法文档的一个框架。该框架最主要的功能是将Controller的方法进行可视化的展现，像方法注释，方法参数，方法返回值等都提供了相应的用户界面，尤其是对JSON参数的支持。同时可以结合swagger-ui可以对用户界面进行不同程度的定制，也可以对方法进行一个简单的测试。

1.2.code repository

• github:https://github.com/springdox/springdox
• maven:http://www.mvnrepository.com/artifact/com.mangofactory/swagger-springmvc

1.3.演示项目

• 官方：https://github.com/adrianbk/swagger-springmvc-demo
• 民间：https://github.com/qq291462491/bugkillers

2.1.环境准备

• idea intellij 13+
• Oracle java 1.6
• Gradle 2.0 +

2.2.项目搭建

2.2.1.jar仓库

Maven

<repositories>     <repository>       <id>jcenter-release</id>       <name>jcenter</name>       <url>http://oss.jfrog.org/artifactory/oss-release-local/</url>     </repository> </repositories>   <dependency>     <groupId>com.mangofactory</groupId>     <artifactId>swagger-springmvc</artifactId>     <version>1.0.0</version> </dependency>

Gradle

repositories {     jcenter() }   compile "com.mangofactory:swagger-springmvc:1.0.0"

2.2.2.相关依赖

• As of v0.9.5 all dependencies on scala have been removed.
• Spring 3.2.x or above
• jackson 2.4.4
• guava 15.0

2.2.3.编写配置文件

编写一个Java文件，并使用注解：

• @Configuration 配置注解，自动在本类上下文加载一些环境变量信息
• @EnableWebMvc 
• @EnableSwagger 使swagger生效
• @ComponentScan("com.myapp.packages") 需要扫描的包路径

示例：

package org.bugkillers.back.swagger;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/**
 * 使用注解的方式来扫描API
 * 无需在Spring的xml配置文件来配置，由 @see @EnableWebMvc 代替
 * <p/>
 * <p> @author 刘新宇
 *
 * <p> @date 2015年1月30日 下午1:18:48
 * <p> @version 0.0.1
 */
@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan(basePackages ={"com.ak.swaggerspringmvc.shared.controller", "com.ak.spring3.music"})
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
   private SpringSwaggerConfig springSwaggerConfig;
   @Autowired
   public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
      this.springSwaggerConfig = springSwaggerConfig;
   }
   /**
    * 链式编程 来定制API样式
    * 后续会加上分组信息
    * @return
    */
   @Bean
   public SwaggerSpringMvcPlugin customImplementation(){
      return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
            .apiInfo(apiInfo())
            .includePatterns(".*")
//            .pathProvider(new GtPaths())
            .apiVersion("0.0.1")
            .swaggerGroup("user");
   }
    private ApiInfo apiInfo() {
      ApiInfo apiInfo = new ApiInfo(
              "bugkillers-back API",
              "bugkillers 后台API文档",
              "<a href="http://127.0.0.1:9081/api" "="" style="color: rgb(59, 115, 175); text-decoration: none; border-radius: 0px !important; border: 0px !important; bottom: auto !important; float: none !important; height: auto !important; left: auto !important; margin: 0px !important; outline: 0px !important; overflow: visible !important; padding: 0px !important; position: static !important; right: auto !important; top: auto !important; vertical-align: baseline !important; width: auto !important; box-sizing: content-box !important; min-height: inherit !important; background: none !important;">http://127.0.0.1:9081/api",
              "bugkillers@163.com",
              "My License",
              "My Apps API License URL"
        );
      return apiInfo;
    }
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
      configurer.enable();
    }
     
    class GtPaths extends SwaggerPathProvider{
        @Override
        protected String applicationPath() {
            return "/restapi";
        }
        @Override
        protected String getDocumentationPath() {
            return "/restapi";
        }
    }
     
}

 

 也可以自己不写配置类，直接使用默认的实现类，在Spring的配置文件中共配置：（不推荐）

1 2	<mvc:annotation-driven/> <!-- Required so swagger-springmvc can access spring"s RequestMappingHandlerMapping  --> <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

 

2.2.4.与swagger-ui集成

方式一：

• Note: Only use this option if you don"t need to customize any of the swagger-ui static content, otherwise use option 2.
• Use the web-jar which packages all of the swagger-ui static content.
• Requires that your app is using the servlet 3 specification.
• For non-spring boot applications some extra spring configuration (ResourceHandler"s) is required. See: https://github.com/adrianbk/swagger-springmvc-demo/tree/master/swagger-ui

1 2 3 4

dependencies {   ...   compile "org.ajar:swagger-spring-mvc-ui:0.4" }

方式二：（推荐）

• Manually copy all of the static content swagger-ui"s dist directory (https://github.com/wordnik/swagger-ui/tree/master/dist)
• Provide the necessary view resolvers and resource handlers to serve the static content.
• Consult the spring documentation on serving static resources.

The following is one way to serve static content from /src/main/webapp

1 2 3 4 5

<!-- Direct static mappings --> <mvc:resources mapping="*.html" location="/"/>   <!-- Serve static content--> <mvc:default-servlet-handler/>

2.6.5.Controller配置

使用注解对Controller进行配置：

• @Api 配置方法API
• @ApiOperation API的操作 GET PUT DELETE POST
• @ApiParam API的方法参数描述

示例Controller：

package org.bugkillers.back.user.controller;
import java.util.List;
import org.bugkillers.back.bean.User;
import org.bugkillers.back.result.Result;
import org.bugkillers.back.user.service.UserService;
import org.bugkillers.back.util.ResultUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
/**
 * 用户操作Controller
 * <p/>
 * <p>
 *
 * @author 刘新宇
 *
 *         <p>
 * @date 2015年1月30日 上午10:50:34
 *       <p>
 * @version 0.0.1
 */
@Api(value = "user-api", description = "有关于用户的CURD操作", position = 5)
@Controller
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService service;
    /**
     * 注册用户
     * @param user
     */
    @ApiOperation(value = "注册", notes = "注册用户", position = 3)
    @ResponseBody
    @RequestMapping(value = { "/regist" }, method = RequestMethod.POST)
    public ResponseEntity<?> regist(@RequestBody User user) {
        service.save(user);
        Result<String> result = ResultUtil.buildSuccessResult("注册成功");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据pk查找用户
     * @param userPk
     * @return
     */
    @ApiOperation(value = "根据pk查找用户", notes = "返回用户实体对象", response = User.class, position = 2)
    @ResponseBody
    @RequestMapping(value = { "/{userPk}" }, method = RequestMethod.GET)
    public ResponseEntity<?> findByPk(
            @ApiParam(value = "填写Pk", allowableValues = "range[1,5]", required = true, defaultValue = "userPk", allowMultiple = true) @PathVariable("userPk") Integer userPk) {
        Result<User> result = ResultUtil.buildSuccessResult(service.findByPk(userPk));
        return new ResponseEntity<Result<User>>(result, HttpStatus.OK);
    }
     
    /**
     * 测试
     * @param who
     * @return
     */
    @ApiOperation(value = "Hellow World", notes = "测试功能", position = 1)
    @ResponseBody
    @RequestMapping(value = { "/hello/{who}" }, method = RequestMethod.GET)
    public ResponseEntity<?> hello(
            @ApiParam(value = "填写名称") @PathVariable("who") String who) {
        Result<String> result = ResultUtil.buildSuccessResult( "Hello guys" + " " + who + "!");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
    /**
     * 查询所有
     * @return
     */
    @ApiOperation(value = "获取所有用户", notes = "返回用户实体对象集合", position = 5)
    @RequestMapping(value = "/findAll", method = RequestMethod.GET)
    public @ResponseBody ResponseEntity<?>  findAll() {
        Result<List<User>> result = ResultUtil.buildSuccessResult( service.findAll());
        return  new ResponseEntity<Result<List<User>>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据用户pk更新实体
     * @param userPk  用户pk
     * @param user 返回更新后的实体
     * @return
     */
    @ApiOperation(value = "更新用户", notes = "返回更新的用户实体对象",position = 5)
    @RequestMapping(value = "/update/{userPk}", method = RequestMethod.PUT)
    public ResponseEntity<?> updateByPk(
            @PathVariable("userPk") Integer userPk, @RequestBody User user) {
        user.setPk_user(userPk);
        service.update(user);
        Result<User> result = ResultUtil.buildSuccessResult(user);
        return new ResponseEntity<Result<User>>(result, HttpStatus.OK);
    }
     
    /**
     * 根据用户pk删除实体
     * @param userPk  用户pk
     * @return
     */
    @ApiOperation(value = "删除用户", notes = "根据pk删除用户",position = 5)
    @RequestMapping(value = "/delete/{userPk}", method = RequestMethod.GET)
    public ResponseEntity<?> deleteByPk(
            @PathVariable("userPk") Integer userPk) {
        service.delete(userPk);
        Result<String> result = ResultUtil.buildSuccessResult("删除成功");
        return new ResponseEntity<Result<String>>(result, HttpStatus.OK);
    }
}

2.2.6.启动中间件

项目配置了Jetty或者Tomcat等Web容器的话，在对应的Controller配置好的话就可以启动看效果了。

• 访问本机：http://127.0.0.1:9081/api

• 远程示例：http://115.29.170.213/api

2.2.7.需求定制

• 分组信息定制
• Url定制
• Http相应定制

 

Swagger很好的为我们在开发RESTful框架应用时，前后台分离的情况下提供了很有效的解决方案，上手迅速，操作简单，界面精简，功能完善，满足各种定制化的需求，是在使用Spring MVC做Web开发时的不二选择。通过对swagger的学习，增强了英语交流的能力，改变了以前的学习方法，收获了很多，同时也也得感谢国外友人的悉心帮助~技术无国界~

3.1  Guava工具类的使用  http://ifeve.com/google-guava/

Guava工程包含了若干被Google的 Java项目广泛依赖 的核心库，例如：集合 [collections] 、缓存 [caching] 、原生类型支持 [primitives support] 、并发库 [concurrency libraries] 、通用注解 [common annotations] 、字符串处理 [string processing] 、I/O 等等

3.2  Gradle构建工具的使用  http://ifeve.com/google-guava/

配置更加简洁，支持Maven，好多开源项目已经从Maven转到Gradle。

3.3  Groovy语言 http://groovy.codehaus.org/User+Guide

和scala、clojure等同是在JVM上运行的脚本语言，丰富的类库，和Java互通，可以作为Java程序员的第二语言。

3.4  链式编程 （return this）

Java中类似Swagger配置文件SwaggerSpringMvcPlugin

JQuery中类似 $("#p1").css("color","red").slideUp(2000).slideDown(2000);