Swagger框架学习分享

Created and last modified by 刘新宇大约1分钟曾经

pageId=162045803#page-metadata-start" class="assistive" style="color:rgb(59,115,175); text-decoration:none; border:0px; height:1px; margin:-1px; overflow:hidden; padding:0px; position:absolute; width:1px">转至元数据起始

一、背景介绍

1.1.项目简单介绍

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

1.2.code repository

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

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

<!--

 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/

Guavaproject包括了若干被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);

在公司的Wiki上写的博文。由于外面訪问不了公司的内网，故贴过来给须要的小伙伴们分享一下,有疑问的能够随时交流。