zoukankan      html  css  js  c++  java

  • Swagger框架学习分享

    转至元数据结尾
    转至元数据起始

    一、背景介绍

    1.1.项目简单介绍

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

    1.2.code repository

    1.3.演示项目

    二、开发准备

    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;  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配置好的话就能够启动看效果了。

    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上写的博文。由于外面訪问不了公司的内网，故贴过来给须要的小伙伴们分享一下,有疑问的能够随时交流。
  • 相关阅读:
    /bin/bash^M：损坏的解释器: 没有那个文件或目录
    QT槽函数处理线程
    Strategy策略模式
    Proxy代理模式
    Ubuntu系统修改BIOS时间问题
    Ubuntu下安装Goldendict（翻译软件）
    自定义QMenu
    C connect实现Timeout效果（Windows）
    059 Python计算生态概览
    058 程序设计方法学小结
  • 原文地址：https://www.cnblogs.com/wzzkaifa/p/6984559.html
Copyright © 2011-2022 走看看