澳门新萄京官方网站-www.8455.com-澳门新萄京赌场网址

澳门新萄京官方网站:Swagger2在SpringBoot环境下的

2019-05-02 作者:www.8455.com   |   浏览(110)

Swagger2在SpringBoot环境下的应用

集成步骤

第四章 springboot swagger,springbootswagger

注:本文参考自

 

swagger用于定义API文档。

好处:

  • 前后端分离开发
  • API文档非常明确
  • 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
  • 传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件)
  • spring-boot与swagger的集成简单的一逼

1、项目结构

和上一节一样,没有改变。

2、pom.xml

引入了两个jar。

澳门新萄京官方网站 1 1 <dependency> 2 <groupId>io.springfox</groupId> 3 <artifactId>springfox-swagger2</artifactId> 4 <version>2.2.2</version> 5 </dependency> 6 <dependency> 7 <groupId>io.springfox</groupId> 8 <artifactId>springfox-swagger-ui</artifactId> 9 <version>2.2.2</version> 10 </dependency> View Code

3、Application.java

澳门新萄京官方网站 2 1 package com.xxx.firstboot; 2 3 import org.springframework.boot.SpringApplication; 4 import org.springframework.boot.autoconfigure.SpringBootApplication; 5 6 import springfox.documentation.swagger2.annotations.EnableSwagger2; 7 8 @SpringBootApplication //same as @[email protected][email protected] 9 @EnableSwagger2 //启动swagger注解 10 public class Application { 11 12 public static void main(String[] args) { 13 SpringApplication.run(Application.class, args); 14 } 15 16 } View Code

说明:

  • 引入了一个注解@EnableSwagger2来启动swagger注解。(启动该注解使得用在controller中的swagger注解生效,覆盖的范围由@ComponentScan的配置来指定,这里默认指定为根路径"com.xxx.firstboot"下的所有controller)

4、UserController.java

澳门新萄京官方网站 3 1 package com.xxx.firstboot.web; 2 3 import org.springframework.beans.factory.annotation.Autowired; 4 import org.springframework.web.bind.annotation.RequestHeader; 5 import org.springframework.web.bind.annotation.RequestMapping; 6 import org.springframework.web.bind.annotation.RequestMethod; 7 import org.springframework.web.bind.annotation.RequestParam; 8 import org.springframework.web.bind.annotation.RestController; 9 10 import com.xxx.firstboot.domain.User; 11 import com.xxx.firstboot.service.UserService; 12 13 import io.swagger.annotations.Api; 14 import io.swagger.annotations.ApiImplicitParam; 15 import io.swagger.annotations.ApiImplicitParams; 16 import io.swagger.annotations.ApiOperation; 17 import io.swagger.annotations.ApiResponse; 18 import io.swagger.annotations.ApiResponses; 19 20 @RestController 21 @RequestMapping("/user") 22 @Api("userController相关api") 23 public class UserController { 24 25 @Autowired 26 private UserService userService; 27 28 // @Autowired 29 // private MyRedisTemplate myRedisTemplate; 30 31 @ApiOperation("获取用户信息") 32 @ApiImplicitParams({ 33 @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"), 34 @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna") 35 }) 36 @ApiResponses({ 37 @ApiResponse(code=400,message="请求参数没填好"), 38 @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") 39 }) 40 @RequestMapping(value="/getUser",method=RequestMethod.GET) 41 public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) { 42 return userService.getUser(username,password); 43 } 44 45 // @RequestMapping("/testJedisCluster") 46 // public User testJedisCluster(@RequestParam("username") String username){ 47 // String value = myRedisTemplate.get(MyConstants.USER_FORWARD_CACHE_PREFIX, username); 48 // if(StringUtils.isBlank(value)){ 49 // myRedisTemplate.set(MyConstants.USER_FORWARD_CACHE_PREFIX, username, JSON.toJSONString(getUser())); 50 // return null; 51 // } 52 // return JSON.parseObject(value, User.class); 53 // } 54 55 } View Code

说明:

  • @Api:用在类上,说明该类的作用
  • @ApiOperation:用在方法上,说明方法的作用
  • @ApiImplicitParams:用在方法上包含一组参数说明
  • @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    • paramType:参数放在哪个地方
      • header-->请求参数的获取:@RequestHeader
      • query-->请求参数的获取:@RequestParam
      • path(用于restful接口)-->请求参数的获取:@PathVariable
      • body(不常用)
      • form(不常用)
    • name:参数名
    • dataType:参数类型
    • required:参数是否必须传
    • value:参数的意思
    • defaultValue:参数的默认值
  • @ApiResponses:用于表示一组响应
  • @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    • code:数字,例如400
    • message:信息,例如"请求参数没填好"
    • response:抛出异常的类

以上这些就是最常用的几个注解了。

具体其他的注解,查看:

 

测试:

启动服务,浏览器输入""

澳门新萄京官方网站 4

最上边一个红框:@Api

GET红框:method=RequestMethod.GET

右边红框:@ApiOperation

parameter红框:@ApiImplicitParams系列注解

response messages红框:@ApiResponses系列注解

输入参数后,点击"try it out!",查看响应内容:

澳门新萄京官方网站 5

 

springboot swagger,springbootswagger 注:本文参考自 swagger用于定义API文档。 好处: 前后端分离开发 API文档...

第五章 springboot mybatis,springbootmybatis

springboot集成了springJDBC与JPA,但是没有集成mybatis,所以想要使用mybatis就要自己去集成。集成方式相当简单。

1、项目结构

澳门新萄京官方网站 6

 

2、pom.xml

澳门新萄京官方网站 7 1 <!-- 与数据库操作相关的依赖 --> 2 <dependency> 3 <groupId>org.springframework.boot</groupId> 4 <artifactId>spring-boot-starter-jdbc</artifactId> 5 </dependency> 6 7 <!-- 使用数据源 --> 8 <dependency> 9 <groupId>com.alibaba</groupId> 10 <artifactId>druid</artifactId> 11 <version>1.0.14</version> 12 </dependency> 13 14 <!-- mysql --> 15 <dependency> 16 <groupId>mysql</groupId> 17 <artifactId>mysql-connector-java</artifactId> 18 <scope>runtime</scope> 19 </dependency> 20 21 <!-- mybatis --> 22 <dependency> 23 <groupId>org.mybatis</groupId> 24 <artifactId>mybatis</artifactId> 25 <version>3.2.8</version> 26 </dependency> 27 <dependency> 28 <groupId>org.mybatis</groupId> 29 <artifactId>mybatis-spring</artifactId> 30 <version>1.2.2</version> 31 </dependency> View Code

说明:

  • spring-boot-starter-jdbc:引入与数据库操作相关的依赖,例如daoSupport等

  • druid:阿里巴巴的数据源

  • mysql-connector-java:mysql连接jar,scope为runtime
  • mybatis mybatis-spring:mybatis相关jar

 

3、application.properties

澳门新萄京官方网站 81 jdbc.driverClassName = com.mysql.jdbc.Driver 2 jdbc.url = jdbc:mysql://xxx:3306/mytestdb?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=utf-8 3 jdbc.username = root 4 jdbc.password = vvvxxx 5 6 mybatis.typeAliasesPackage=com.xxx.firstboot.domain 7 mybatis.mapperLocations=classpath:mapper/*.xml View Code

说明:

  • mybatis.typeAliasesPackage:指定domain类的基包,即指定其在*Mapper.xml文件中可以使用简名来代替全类名(看后边的UserMapper.xml介绍)
  • mybatis.mapperLocations:指定*Mapper.xml的位置

 

4、com.xxx.firstboot.common.MyBatisConfig

作用:mybatis与springboot集成的入口

澳门新萄京官方网站 9 1 package com.xxx.firstboot.common; 2 3 import java.util.Properties; 4 5 import javax.sql.DataSource; 6 7 import org.apache.ibatis.session.SqlSessionFactory; 8 import org.mybatis.spring.SqlSessionFactoryBean; 9 import org.mybatis.spring.annotation.MapperScan; 10 import org.springframework.beans.factory.annotation.Autowired; 11 import org.springframework.context.annotation.Bean; 12 import org.springframework.context.annotation.Configuration; 13 import org.springframework.core.env.Environment; 14 import org.springframework.core.io.support.PathMatchingResourcePatternResolver; 15 16 import com.alibaba.druid.pool.DruidDataSourceFactory; 17 18 /** 19 * springboot集成mybatis的基本入口 20 * 1)创建数据源 21 * 2)创建SqlSessionFactory 22 */ 23 @Configuration //该注解类似于spring配置文件 24 @MapperScan(basePackages="com.xxx.firstboot.mapper") 25 public class MyBatisConfig { 26 27 @Autowired 28 private Environment env; 29 30 /** 31 * 创建数据源 32 * @Primary 该注解表示在同一个接口有多个实现类可以注入的时候,默认选择哪一个,而不是让@autowire注解报错 33 */ 34 @Bean 35 //@Primary 36 public DataSource getDataSource() throws Exception{ 37 Properties props = new Properties(); 38 props.put("driverClassName", env.getProperty("jdbc.driverClassName")); 39 props.put("url", env.getProperty("jdbc.url")); 40 props.put("username", env.getProperty("jdbc.username")); 41 props.put("password", env.getProperty("jdbc.password")); 42 return DruidDataSourceFactory.createDataSource(props); 43 } 44 45 /** 46 * 根据数据源创建SqlSessionFactory 47 */ 48 @Bean 49 public SqlSessionFactory sqlSessionFactory(DataSource ds) throws Exception{ 50 SqlSessionFactoryBean fb = new SqlSessionFactoryBean(); 51 fb.setDataSource(ds);//指定数据源(这个必须有,否则报错) 52 //下边两句仅仅用于*.xml文件,如果整个持久层操作不需要使用到xml文件的话(只用注解就可以搞定),则不加 53 fb.setTypeAliasesPackage(env.getProperty("mybatis.typeAliasesPackage"));//指定基包 54 fb.setMapperLocations(new PathMatchingResourcePatternResolver().getResources(env.getProperty("mybatis.mapperLocations")));//指定xml文件位置 55 56 return fb.getObject(); 57 } 58 59 } View Code

说明:

  • 类上边添加两个
    • @Configuration注解(该注解类似于spring的配置文件)
    • @MapperScan注解,指定扫描的mapper接口所在的包
  • 在该类中,注入了Environment实例,使用该实例可以去读取类路径下application.properties文件中的内容,读取文件内容的三种方式,见第二章 第二个spring-boot程序
  • 在该类中,使用druid数据源定义了数据源Bean,spring-boot默认使用的是tomcat-jdbc数据源,这是springboot官方推荐的数据源(性能和并发性都很好)
  • 根据数据源生成SqlSessionFactory
    • 值得注意的是,数据源是必须指定的,否则springboot启动不了
    • typeAliasesPackage和mapperLocations不是必须的,如果整个项目不需要用到*Mapper.xml来写SQL的话(即只用注解就可以搞定),那么不需要配
  • @Primary注解:指定在同一个接口有多个实现类可以注入的时候,默认选择哪一个,而不是让@Autowire注解报错(一般用于多数据源,多个SqlSessionFactory的情况下)

这样之后,在项目中再使用springboot就和在ssm中(配置完成后)使用一样了。

 

5、com.xxx.firstboot.mapper.UserMapper

澳门新萄京官方网站 10 1 package com.xxx.firstboot.mapper; 2 3 import org.apache.ibatis.annotations.Insert; 4 import org.apache.ibatis.annotations.Param; 5 6 import com.xxx.firstboot.domain.User; 7 8 public interface UserMapper { 9 10 @Insert("INSERT INTO tb_user(username, password) VALUES(#{username},#{password})") 11 public int insertUser(@Param("username") String username, @Param("password") String password); 12 13 /** 14 * 插入用户,并将主键设置到user中 15 * 注意:返回的是数据库影响条数,即1 16 */ 17 public int insertUserWithBackId(User user); 18 } View Code

说明:该接口中有两个方法,

  • 一个普通插入:直接用注解搞定
  • 一个插入返回主键:需要使用xml来搞定

澳门新萄京官方网站 11 1 <?xml version="1.0" encoding="UTF-8" ?> 2 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "; 3 4 <!-- 指定工作空间,要与接口名相同,源代码没有去看,猜测应该是通过"这里的namespace.下边方法的id"来定位方法的 --> 5 <mapper namespace="com.xxx.firstboot.mapper.UserMapper"> 6 7 <!-- 若不需要自动返回主键,将useGeneratedKeys="true" keyProperty="id"去掉即可(当然如果不需要自动返回主键,直接用注解即可) --> 8 <insert id="insertUserWithBackId" parameterType="User" useGeneratedKeys="true" keyProperty="id" > 9 <![CDATA[ 10 INSERT INTO tb_user 11 ( 12 username, 13 password 14 ) 15 VALUES 16 ( 17 #{username, jdbcType=VARCHAR}, 18 #{password, jdbcType=VARCHAR} 19 ) 20 ]]> 21 </insert> 22 23 </mapper> View Code

 

6、com.xxx.firstboot.dao.UserDao

澳门新萄京官方网站 12 1 package com.xxx.firstboot.dao; 2 3 import org.springframework.beans.factory.annotation.Autowired; 4 import org.springframework.stereotype.Repository; 5 6 import com.xxx.firstboot.domain.User; 7 import com.xxx.firstboot.mapper.UserMapper; 8 9 @Repository 10 public class UserDao { 11 12 @Autowired 13 private UserMapper userMapper; 14 15 public int insertUser(String username, String password){ 16 return userMapper.insertUser(username, password); 17 } 18 19 public int insertUserWithBackId(User user){ 20 return userMapper.insertUserWithBackId(user); 21 } 22 23 } View Code

 

7、com.xxx.firstboot.service.UserService

澳门新萄京官方网站 13 1 package com.xxx.firstboot.service; 2 3 import org.springframework.beans.factory.annotation.Autowired; 4 import org.springframework.stereotype.Service; 5 6 import com.xxx.firstboot.dao.UserDao; 7 import com.xxx.firstboot.domain.User; 8 9 @Service 10 public class UserService { 11 12 @Autowired 13 private UserDao userDao; 14 15 public boolean addUser(String username, String password){ 16 return userDao.insertUser(username, password)==1?true:false; 17 } 18 19 public User addUserWithBackId(String username, String password){ 20 User user = new User(); 21 user.setUsername(username); 22 user.setPassword(password); 23 userDao.insertUserWithBackId(user);//该方法后,主键已经设置到user中了 24 return user; 25 } 26 27 } View Code

 

8、com.xxx.firstboot.controller.UserController

澳门新萄京官方网站 14 1 package com.xxx.firstboot.web; 2 3 import org.springframework.beans.factory.annotation.Autowired; 4 import org.springframework.web.bind.annotation.RequestMapping; 5 import org.springframework.web.bind.annotation.RequestMethod; 6 import org.springframework.web.bind.annotation.RequestParam; 7 import org.springframework.web.bind.annotation.RestController; 8 9 import com.xxx.firstboot.domain.User; 10 import com.xxx.firstboot.service.UserService; 11 12 import io.swagger.annotations.Api; 13 import io.swagger.annotations.ApiImplicitParam; 14 import io.swagger.annotations.ApiImplicitParams; 15 import io.swagger.annotations.ApiOperation; 16 import io.swagger.annotations.ApiResponse; 17 import io.swagger.annotations.ApiResponses; 18 19 @RestController 20 @RequestMapping("/user") 21 @Api("userController相关api") 22 public class UserController { 23 24 @Autowired 25 private UserService userService; 26 27 @ApiOperation("添加用户") 28 @ApiImplicitParams({ 29 @ApiImplicitParam(paramType="query",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"), 30 @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna") 31 }) 32 @ApiResponses({ 33 @ApiResponse(code=400,message="请求参数没填好"), 34 @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") 35 }) 36 @RequestMapping(value="/addUser",method=RequestMethod.POST) 37 public boolean addUser(@RequestParam("username") String username, 38 @RequestParam("password") String password) { 39 return userService.addUser(username,password); 40 } 41 42 @ApiOperation("添加用户且返回已经设置了主键的user实例") 43 @ApiImplicitParams({ 44 @ApiImplicitParam(paramType="query",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"), 45 @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna") 46 }) 47 @ApiResponses({ 48 @ApiResponse(code=400,message="请求参数没填好"), 49 @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") 50 }) 51 @RequestMapping(value="/addUserWithBackId",method=RequestMethod.POST) 52 public User addUserWithBackId(@RequestParam("username") String username, 53 @RequestParam("password") String password) { 54 return userService.addUserWithBackId(username, password); 55 } 56 } View Code

 

测试:

进入项目的pom.xml文件所在目录,执行"mvn spring-boot:run"(这是最推荐的spring-boot的运行方式),另外一种在主类上右击-->"run as"-->"java application"不常用

springboot mybatis,springbootmybatis springboot集成了springJDBC与JPA,但是没有集成mybatis,所以想要使用mybatis就要自己去集成。集成方式相当...

Swagger与SpringMVC项目整合

为了方便的管理项目中API接口,在网上找了好多关于API接口管理的资料,感觉目前最流行的莫过于Swagger了,功能强大,UI界面漂亮,并且支持在线测试等等,所以本人仔细研究了下Swagger的使用,下面就如何将Swagger与个人的SpringMVC项目进行整合做详细说明:

最终API管理界面: 
澳门新萄京官方网站 15

详细步骤:

1. 集成Swagger

1、在pom.xml中引用度swagger依赖包

Step1:项目中引入相关jar包:

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <version.spring>3.2.9.RELEASE</version.spring>
        <version.jackson>2.4.4</version.jackson>
    </properties>

    <dependencies>
        ....
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.9.5</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>${version.jackson}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${version.jackson}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${version.jackson}</version>
        </dependency>
    </dependencies>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30

1.1 添加依赖

<!--swagger2 start-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.6.1</version>

</dependency>

<!--引入swagger-ui包-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

 

<dependency>

Step2:添加自定义config文件

package com.spg.apidoc.common.configer;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * 项目名称:apidoc
 *
 * @description:
 * @author Wind-spg
 * @create_time:2015年2月10日 上午10:27:51
 * @version V1.0.0
 *
 */
@Configuration
@EnableSwagger
// Loads the spring beans required by the framework
public class MySwaggerConfig
{

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(
                ".*?");
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title", 
                "My Apps API Description",
                "My Apps API terms of service", 
                "My Apps API Contact Email", 
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61

1.2 配置类

package com.inn.demo.config;

 

import org.springframework.beans.factory.annotation.Value;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

 

@Configuration

@EnableSwagger2

public class SwaggerConfiguration extends WebMvcConfigurerAdapter {

//生产关闭swagger

@Value("${swagger.enable}")

private boolean enableSwagger;

 

// /**

// * 访问swagger ui 出现404时可以把注释去掉试试

// * 解决资源系统资源目录与swagger ui资源目录冲突问题

// * 这个地方要重新注入一下资源文件,不然不会注入资源的,也没有注入requestHandlerMappping,相当于xml配置的swagger资源配置

// * <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>

// * <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

// * @param registry

// */

// @Override

// public void addResourceHandlers(ResourceHandlerRegistry registry) {

// registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");

// registry.addResourceHandler("swagger-ui.html")

// .addResourceLocations("classpath:/META-INF/resources/");

// registry.addResourceHandler("/webjars/**")

// .addResourceLocations("classpath:/META-INF/resources/webjars/");

// super.addResourceHandlers(registry);

// }

 

// /**

// * 支持分组 groupName

// */

// @Bean(value = "solrRestApi")

// public Docket createSolrRestApi() {

// return new Docket(DocumentationType.SWAGGER_2)

// .apiInfo(apiInfo()).groupName("Solr Demo模块")

// .enable(enableSwagger)

// .select()

// .apis(RequestHandlerSelectors.basePackage("com.inn.demo.modules.solr.web"))

// .paths(PathSelectors.any())

// .build();

// }

 

@Bean(value = "userRestApi")

public Docket createUserRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

//.groupName("用户管理")

.enable(enableSwagger)

.globalOperationParameters(createCommonParams())//公共参数

.select()

.apis(RequestHandlerSelectors.basePackage("com.inn.demo.modules.user.web"))

.paths(PathSelectors.any())

.build();

}

 

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Demo APIs")

.description("应用实例")

//.termsOfServiceUrl(";)

//.contact(new Contact("开发者1", "", "xxx@163.com"))

.version("1.0")

.build();

}

/**
 * 创建公共参数
 * @return
 */
private List<Parameter> createCommonParams() {
    //添加head参数start
    List<Parameter> pars = new ArrayList<Parameter>();

    ParameterBuilder tokenPar = new ParameterBuilder();
    tokenPar.name("x-access-token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();

    pars.add(tokenPar.build());

    return pars;
    //添加head参数end
}

}

 

<groupId>io.springfox</groupId>

Step3:将此配置加入到Spring容器中,如下:

<bean class="com.spg.apidoc.common.configer.MySwaggerConfig" />
  • 1

1.3 注解使用

作用范围

API

使用位置

对象属性

@ApiModelProperty

用在出入参数对象的字段上

协议集描述

@Api

用于controller类上

协议描述

@ApiOperation

用在controller的方法上

Response集

@ApiResponses

用在controller的方法上

Response

@ApiResponse

用在 @ApiResponses里边

非对象参数集

@ApiImplicitParams

用在controller的方法上

非对象参数描述

@ApiImplicitParam

用在@ApiImplicitParams的方法里边

描述返回对象的意义

@ApiModel

用在返回对象类上

ApiImplicitParam的相关属性

属性

取值

作用

paramType

path

query

body

header

form

参数放在哪个地方:必须要有这个属性

header:header中提交:@RequestHeader获取

query :key=value提交:@RequestParam获取

path  :地址中提交:@PathVariable获取

body  :json流提交 :@RequestBody获取(限POST)

form  :表单提交:@RequestParam获取(限POST)

dataType

Long

String

参数的数据类型 只作为标志说明,并没有实际验证

name

 

接收参数名

value

 

接收参数的意义描述

required

 

参数是否必填

 

TRUE

必填

 

FALSE

非必填

defaultValue

 

默认值

ApiImplicitParam 与 ApiParam 的区别

ApiImplicitParam: 

  • 对Servlets或者非 JAX-RS的环境,只能使用 ApiImplicitParam。
  • 在使用上,ApiImplicitParam比ApiParam具有更少的代码侵入性,只要写在方法上就可以了,但是需要提供具体的属性才能配合swagger ui解析使用。
  • ApiParam只需要较少的属性,与swagger ui配合更好。

 

代码实例:

@RestController

@RequestMapping(value = "/user")

@Api(value = "/user", description = "人员基本信息 ")

public class UserController {

 

static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());

 

@ApiOperation(value = "获取用户列表", notes = "")

@RequestMapping(value = {"/list"}, method = RequestMethod.GET)

public List<User> getUserList() {

List<User> r = new ArrayList<User>(users.values());

return r;

}

 

@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")

@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")

@RequestMapping(value = "add", method = RequestMethod.POST)

public String postUser(@RequestBody User user) {

users.put(user.getId(), user);

return "success";

}

 

@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")

@ApiParam(name = "id", value = "用户ID", required = true)

@RequestMapping(value = "/get/{id}", method = RequestMethod.GET)

public User getUser(@PathVariable(value = "id") String id) {

return users.get(id);

}

 

@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")

@RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)

public String putUser(@PathVariable @ApiParam(name = "id", value = "用户ID", required = true) String id,

@RequestBody @ApiParam(name = "user", value = "用户详细实体user", required = true) User user) {

User u = users.get(id);

u.setName(user.getName());

u.setAge(user.getAge());

users.put(id, u);

return "success";

}

 

@ApiOperation(value = "更新用户名称和年龄", notes = "更新用户名称和年龄")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String",paramType = "path"),

@ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String",paramType = "query"),

@ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "Integer",paramType = "query"),

@ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User",paramType = "body"),

@ApiImplicitParam(name = "headerName", value = "Header信息", required = true, dataType = "String",paramType = "header")

})

@RequestMapping(value = "/update/info/{id}", method = RequestMethod.POST)

public String updateUserNameAndAge(@PathVariable(value = "id") String id,

@RequestParam(value = "name") String name,

@RequestParam(value = "age") Integer age,

@RequestHeader(value = "headerName") String headerName,

@RequestBody User user) {

User u = users.get(id);

u.setName(name);

u.setAge(age);

users.put(id, u);

return "success";

}

 

@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")

@ApiParam(name = "id", value = "用户ID", required = true)

@RequestMapping(value = "/delete/{id}", method = RequestMethod.DELETE)

public String deleteUser(@PathVariable String id) {

users.remove(id);

return "success";

}

 

@ApiOperation(value="删除用户-传递数组", notes="删除对象,传递数组")

@RequestMapping(value="/users/deleteByIds", method = RequestMethod.DELETE)

public void deleteUsers(@ApiParam("用户ID数组") @RequestParam Integer[] ids) {

for (int id:ids){

users.remove(id);

}

}

}

User实体类:

 

@JsonInclude(JsonInclude.Include.NON_NULL)

@JsonIgnoreProperties({"handler", "hibernateLazyInitializer"})

@ApiModel(value = "User")

public class User {

@ApiModelProperty(value = "ID")

private String id;

 

@ApiModelProperty(value = "姓名", required = true)

private String name;

 

@ApiModelProperty(value = "年龄")

private Integer age;

 

public String getId() {

return id;

}

 

public void setId(String id) {

this.id = id;

}

 

public String getName() {

return name;

}

 

public void setName(String name) {

this.name = name;

}

 

public Integer getAge() {

return age;

}

 

public void setAge(Integer age) {

this.age = age;

}

}

 

<artifactId>springfox-swagger2</artifactId>

Step4:在代码中添加相关APIAnnotation,如下:

    @ResponseBody
    @RequestMapping(
            value = "addUser", method = RequestMethod.POST, produces = "application/json; charset=utf-8")
    @ApiOperation(value = "添加用户", httpMethod = "POST", response = BaseResultVo.class, notes = "add user")
    public String addUser(@ApiParam(required = true, name = "postData", value = "用户信息json数据") @RequestParam(
            value = "postData") String postData, HttpServletRequest request)
    {
        LOGGER.debug(String.format("at function, %s", postData));
        if (null == postData || postData.isEmpty())
        {
            return super.buildFailedResultInfo(-1, "post data is empty!");
        }

        UserInfo user = JSON.parseObject(postData, UserInfo.class);
        int result = userService.addUser(user);
        return buildSuccessResultInfo(result);
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17

说明: 
其中@ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下: 
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”;其他参数可参考源码; 
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

1.4 访问控制台

 

按以下步骤配置,项目启动后访问:

<version>2.6.1</version>

Step5:添加Swagger UI配置

在GitHub上下载SwaggerUI项目,将dist下所有内容拷贝到本地项目webapp下面,结果目录如下图所示: 
澳门新萄京官方网站 16

1.5 可选配置

在application.properties中加入以下配置,用于设置测试请求的host,默认在swagger ui上做请求测试时都是以/users/1为路径发送请求。

如果需要改变请求的根路径,就需要配置这个参数:

该Host也是swagger-ui发送测试请求的Host, 通常我们会将将接口文档部署在测试服务器,这样就需要设置Host,

否则请求都是通过localhost发送,请求不到测试服务器的接口。

springfox.documentation.swagger.v2.host = yourapp.abc.com

配置获取api docs json数据的请求路径 ,默认为/v2/api-docs:

springfox.documentation.swagger.v2.path = /api

 

</dependency>

Step6:修改index.html

将index.html中修改为{projectname}/api-docs

到此为止,所有配置完成,启动你的项目,访问{projectName}/index.html即可看到如下所示页面: 
澳门新萄京官方网站 17
澳门新萄京官方网站 18

项目最终demo可见个人GitHub 
 
参考: 
 

项目jar包下载:

 

 

        当我们把我们的服务以REST的形式接口暴露出去,其他开发者要调用我们的接口首先要能够详细的了解我们的API,目前几乎所有的开放平台都是把API以文档的形式放在网站上,例如:新浪、淘宝、微信等等。

在开发者调用API之前对一些API说明的理解比较模糊,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力。Swagger就是这样的一个利器,Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

 

下面说一下如何为现有项目添加Swagger

首先添加对Swagger的依赖

<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.9.1</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-core_2.10</artifactId>
<version>1.3.7</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>18.0</version>
</dependency>
<dependency>
<groupId>org.scala-lang</groupId>
<artifactId>scala-library</artifactId>
<version>2.10.0</version>
</dependency>

加入对Swagger的配置类:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import com.wordnik.swagger.model.ApiInfo;

@Configuration
@EnableSwagger
public class MySwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;

/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}

/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple
* swagger groups i.e. same code base multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation(){
SwaggerSpringMvcPlugin ssmp = new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.swaggerGroup("api-docs").build();
return ssmp;
}

private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"tk API SPECIFICATION",
"This is the tk api specification,here you can dig into the details of api and do api testing as well.",
"",
"",
"",
"");
return apiInfo;
}
}

在application.xml中增加配置:

<mvc:annotation-driven/>
<bean id="apiDoc" class="com.tk.framework.rest.framework.swaggerconfig.MySwaggerConfig"/>
<!-- Enable scanning of spring @Configuration classes -->
<context:annotation-config/>
<!-- Enable the default documentation controller-->
<context:component-scan base-package="com.mangofactory.swagger.controllers"/>

<!-- Pick up the bundled spring config-->
<context:component-scan base-package="com.mangofactory.swagger.configuration"/>

接着,给开放API的Resource类加上API Annotation,这样上一步配置的Scanner就能够扫描到该Resource开放的API了。 

@RestController
@RequestMapping(value = "/1/users")
@Api(value = "User", description = "User service api", position = 1)
public class UserResourceV1 extends BaseResources
{
private static final Logger logger = LoggerFactory.getLogger(UserResourceV1.class);
@Autowired
private UserService userService;

@ResourceDescription(Resource="user", Operation="getUser")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ApiOperation(httpMethod = "GET", nickname="getUser", value = "get user by userId")
public ResponseModel getUser(@ApiParam(value = "id for greeting", required = true)@PathVariable String id) throws RestException
{
UserModel u = null;
try
{
u = userService.findById(id);
}
catch (Exception e)
{
logger.error(e.getMessage());
throw new RestException(e.getMessage());
}
ResponseModel r = new ResponseModel();
r.setStatus(200);
r.setResult(u);
return r;
}

}

为Model添加Swagger的Annotation,这样Swagger Scanner可以获取更多关于Model对象的信息。 :

@ApiModel(value="User")
@Entity
@Table(name = "user")
public class UserModel {
/**
* id
*/
@ApiModelProperty(required = true)
private String id;
/**
* 姓名
*/
@ApiModelProperty(required = true)
private String name;
/**
* 年龄
*/
@ApiModelProperty(required = true, allowableValues="range[1,100]")
private Integer age;
/**
* 性别
*/
@ApiModelProperty(required = true, allowableValues = "F,M")
private String sex;
@ApiModelProperty(required = true)
private String password;

……

在Swagger Annotation中:

 

    @API表示一个开放的API,可以通过description简要描述该API的功能。

    在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。

    在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。

    @ApiParam用于描述该API操作接受的参数类型

 

接下来,我们把这些信息和Swagger UI集成,以非常美观,实用的方式把这些API信息展示出来。 

首先,从github(, 把该项目dist目录下的内容拷贝到项目的webapp的目录下。 

澳门新萄京官方网站 19

 

 然后,修改index.jsp, 把Swagger UI对象中的URL替换为自己的API路径:

window.swaggerUi = new SwaggerUi({
url: "/api/api-docs",
dom_id: "swagger-ui-container",

启动项目,最后如下图所示:

 

澳门新萄京官方网站 20

 

 

澳门新萄京官方网站 21

 

澳门新萄京官方网站 22

 

 具有直接测试API的能力:

澳门新萄京官方网站 23

  

 

2. 生成静态API文档pdf

<dependency>

2.1 Maven 配置

======属性配置=======

<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>

<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>

<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>

<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>

<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>

 

=====依赖配置============

<!--离线文档-->

<dependency>

<groupId>org.springframework.restdocs</groupId>

<artifactId>spring-restdocs-mockmvc</artifactId>

<version>1.1.2.RELEASE</version>

<scope>test</scope>

</dependency>

<!--springfox-staticdocs 生成静态文档-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-staticdocs</artifactId>

<version>2.6.1</version>

</dependency>

<!--swagger2 end-->

 

============插件配置==========

<!--通过Asciidoctor使得asciidoc生成其他的文档格式,例如:PDF 或者HTML5-->

<plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<version>1.5.3</version>

<!--生成PDF-->

<dependencies>

<dependency>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctorj-pdf</artifactId>

<version>1.5.0-alpha.14</version>

</dependency>

<!-- Comment this section to use the default jruby artifact provided by the plugin -->

<dependency>

<groupId>org.jruby</groupId>

<artifactId>jruby-complete</artifactId>

<version>1.7.21</version>

</dependency>

</dependencies>

 

<!--文档生成配置-->

<configuration>

<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>

<sourceDocumentName>index.adoc</sourceDocumentName>

<attributes>

<doctype>book</doctype>

<toc>left</toc>

<toclevels>3</toclevels>

<numbered></numbered>

<hardbreaks></hardbreaks>

<sectlinks></sectlinks>

<sectanchors></sectanchors>

<generated>${generated.asciidoc.directory}</generated>

</attributes>

</configuration>

<!--因为每次执行只能处理一个后端,所以对于每个想要的输出类型,都是独立分开执行-->

<executions>

<!--html5-->

<execution>

<id>output-html</id>

<phase>test</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<configuration>

<backend>html5</backend>

<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>

</configuration>

</execution>

<!--pdf-->

<execution>

<id>output-pdf</id>

<phase>test</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<configuration>

<backend>pdf</backend>

<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>

</configuration>

</execution>

</executions>

</plugin>

 

 

<groupId>io.springfox</groupId>

2.2 创建index.adoc文件

路径:项目名/docs/asciidoc/index.adoc

内容:

  1. include::{generated}/overview.adoc[]  
  2. include::{generated}/definitions.adoc[]  
  3. include::{generated}/paths.adoc[]  

 

<artifactId>springfox-swagger-ui</artifactId>

2.3 创建生成pdf、html的测试类

package com.inn.demo;

 

import io.github.robwin.markup.builder.MarkupLanguage;

import io.github.robwin.swagger2markup.GroupBy;

import io.github.robwin.swagger2markup.Swagger2MarkupConverter;

import org.junit.Before;

import org.junit.Test;

import org.junit.runner.RunWith;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

import org.springframework.boot.test.context.SpringBootTest;

import org.springframework.http.MediaType;

import org.springframework.test.context.junit4.SpringRunner;

import org.springframework.test.web.servlet.MockMvc;

import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import org.springframework.web.context.WebApplicationContext;

import springfox.documentation.staticdocs.SwaggerResultHandler;

 

澳门新萄京官方网站:Swagger2在SpringBoot环境下的应用,RESTful风格的Web服务框架。import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

 

@AutoConfigureMockMvc

@AutoConfigureRestDocs(outputDir = "target/generated-snippets")

@RunWith(SpringRunner.class)

@SpringBootTest

public class Swagger2MarkupTest {

private String snippetDir = "target/generated-snippets";

private String outputDir = "target/asciidoc";

 

@Autowired

private WebApplicationContext context;

 

private MockMvc mockMvc;

 

@Before

public void setUp() {

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();

}

 

/**

* 生成api html、pdf

* @throws Exception

*/

@Test

public void Test() throws Exception {

// 得到swagger.json,写入outputDir目录中

mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))

.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())

.andExpect(status().isOk())

.andReturn();

// 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir

// 这个outputDir必须和插件里面<generated></generated>标签配置一致

Swagger2MarkupConverter.from(outputDir   "/swagger.json")

.withPathsGroupedBy(GroupBy.TAGS)// 按tag排序

.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式

.withExamples(snippetDir)

.build()

.intoFolder(outputDir);// 输出

}

}

 

运行测试类即可生成pdf、html

  1. 生成的PDF和HTML文件:target/asciidoc/html and target/asciidoc/pdf  

  2. Swagger-UI 汉化


<version>2.6.1</version>

3.1 添加自定义首页和译文

在resourece目录下创建META-INFresourece目录,然后创建一个名称为"swagger-ui.html" 的HTML文件

澳门新萄京官方网站 24

html内容:

<!DOCTYPE html>

<html>

<head>

<meta charset="UTF-8">

<title>Swagger UI</title>

<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>

<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>

<link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>

<link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>

<link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>

<link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>

<link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

<script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script> <!--国际化操作:选择中文版 -->

<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>

<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

</head>

<body class="swagger-section">

<div id='header'>

<div class="swagger-ui-wrap">

<a id="logo" href="javascript:void(0)">

<img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" />

<span class="logo__title">在线API</span>

</a>

<form id='api_selector'>

<div class='input'>

<select id="select_baseUrl" name="select_baseUrl"></select>

</div>

<div class='input'>

<input placeholder="; id="input_baseUrl" name="baseUrl" type="text"/>

</div>

<div id='auth_container'></div>

<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>

</form>

</div>

</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate></div>

<div id="swagger-ui-container" class="swagger-ui-wrap"></div>

</body>

</html>

大功告成 我们访问 http://localhost:8080/swagger-ui.html 看看显示效果:

澳门新萄京官方网站 25

</dependency>

3.2 更详细的汉化

如果想进一步调整译文,可以在META-INFresourceswebjarsspringfox-swagger-uilang 目录下添加zh-cn.js文件.

澳门新萄京官方网站 26

 

然后在译文(zh-cn.js )内容,如下

'use strict';

 

/* jshint quotmark: double */

window.SwaggerTranslator.learn({

"Warning: Deprecated":"警告:已过时",

"Implementation Notes":"实现备注",

"Response Class":"响应类",

"Status":"状态",

"Parameters":"参数",

"Parameter":"参数",

"Value":"值",

"Description":"描述",

"Parameter Type":"参数类型",

"Data Type":"数据类型",

"Response Messages":"响应消息",

"HTTP Status Code":"HTTP状态码",

"Reason":"原因",

"Response Model":"响应模型",

"Request URL":"请求URL",

"Response Body":"响应体",

"Response Code":"响应码",

"Response Headers":"响应头",

"Hide Response":"隐藏响应",

"Headers":"头",

"Try it out!":"试一下!",

"Show/Hide":"显示/隐藏",

"List Operations":"显示操作",

"Expand Operations":"展开操作",

"Raw":"原始",

"can't parse JSON. Raw result":"无法解析JSON. 原始结果",

"Example Value":"示例",

"Click to set as parameter value":"点击设置参数",

"Model Schema":"模型架构",

"Model":"模型",

"apply":"应用",

"Username":"用户名",

"Password":"密码",

"Terms of service":"服务条款",

"Created by":"创建者",

"See more at":"查看更多:",

"Contact the developer":"联系开发者",

"api version":"api版本",

"Response Content Type":"响应Content Type",

"Parameter content type:":"参数类型:",

"fetching resource":"正在获取资源",

"fetching resource list":"正在获取资源列表",

"Explore":"浏览",

"Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis",

"Can't read from server. It may not have the appropriate access-control-origin settings.":"无法从服务器读取。可能没有正确设置access-control-origin。",

"Please specify the protocol for":"请指定协议:",

"Can't read swagger JSON from":"无法读取swagger JSON于",

"Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI",

"Unable to read api":"无法读取api",

"from path":"从路径",

"server returned":"服务器返回"

});

大功告成!

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>2.6.5</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>2.6.5</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>2.6.5</version>

</dependency>

2、创建swager配置类

package com.vk.liyj.config;

import io.swagger.annotations.ApiOperation;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

* 类描述:配置swagger2信息

*/

@Configuration // 让Spring来加载该类配置

//@EnableWebMvc // 启用Mvc,非springboot框架需要引入注解@EnableWebMvc

@EnableSwagger2 // 启用Swagger2

public class Swagger2Config {

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

// 扫描指定包中的swagger注解

// .apis(RequestHandlerSelectors.basePackage("com.vk.liyj"))

// 扫描所有有注解的api,用这种方式更灵活

.apis(RequestHandlerSelectors

.withMethodAnnotation(ApiOperation.class))

.paths(PathSelectors.any()).build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("基础平台 RESTful APIs")

.description(

"基础平台 RESTful 风格的接口文档,内容详细,极大的减少了前后端的沟通成本,同时确保代码与文档保持高度一致,极大的减少维护文档的时间。")

.termsOfServiceUrl("")

.contact("Xia").version("1.0.0").build();

}

}

通过@Configuration注解,表明它是一个配置类,@EnableSwagger2开启swagger2。apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。

3、编写swagger注解

package com.vk.liyj.model;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

import java.util.Date;

import org.springframework.format.annotation.DateTimeFormat;

import com.fasterxml.jackson.annotation.JsonFormat;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

import com.fasterxml.jackson.annotation.JsonInclude;

/**

* 人员信息表 注解:@ApiModel 和 @ApiModelProperty 用于在通过对象接收参数时在API文档中显示字段的说明

* 注解:@DateTimeFormat 和 @JsonFormat 用于在接收和返回日期格式时将其格式化 实体类对应的数据表为: user_info

*

*

*/

@JsonInclude(JsonInclude.Include.NON_NULL)

@JsonIgnoreProperties({ "handler", "hibernateLazyInitializer" })

@ApiModel(value = "UserInfo")

public class UserInfo {

@ApiModelProperty(value = "ID")

private Integer id;

@ApiModelProperty(value = "用户登录账号", required = true)

private String userNo;

@ApiModelProperty(value = "姓名", required = true)

private String userName;

@ApiModelProperty(value = "姓名拼音")

private String spellName;

@ApiModelProperty(value = "密码", required = true)

private String password;

@ApiModelProperty(value = "手机号", required = true)

private String userPhone;

@ApiModelProperty(value = "性别")

private Integer userGender;

@ApiModelProperty(value = "记录创建时间")

@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")

private Date createTime;

@ApiModelProperty(value = "记录修改时间")

@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")

private Date updateTime;

@JsonFormat(locale = "zh", timezone = "GMT 8", pattern = "yyyy-MM-dd HH:mm:ss")

public Date getCreateTime() {

return createTime;

}

@JsonFormat(locale = "zh", timezone = "GMT 8", pattern = "yyyy-MM-dd HH:mm:ss")

public Date getUpdateTime() {

return updateTime;

}

}

4、控制器类

package com.vk.liyj.controller;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

import java.util.List;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RequestParam;

import com.vk.liyj.model.UserInfo;

import com.vk.liyj.service.UserInfoService;

/**

* 类描述:人员基本信息

*/

@Controller

@RequestMapping(value = "/userInfo")

@Api(value = "UserInfo", description = "人员基本信息 ")

public class UserInfoController {

@Autowired

UserInfoService service;

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

@ApiOperation(value = "查询所有的人员信息", notes = "查询所有的人员信息")

public String selectAllUsers(HttpServletRequest request, HttpServletResponse response) {

List<UserInfo> userList = service.selectAllUsers();

request.setAttribute("userList", userList);

return "userList.jsp";

}

@RequestMapping(value = "selectById", method = RequestMethod.GET)

@ApiOperation(value = "根据用户id查询用户详细信息", notes = "根据用户id查询用户详细信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "type", value = "类型(修改:update;默认为查看)", required = false, paramType = "query"),

@ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query")

})

public String selectById(HttpServletRequest request, HttpServletResponse response,

@RequestParam(value = "id") Integer id, @RequestParam(value = "type") String type) {

UserInfo user = service.selectByPrimaryKey(id);

request.setAttribute("user", user);

if("update".equals(type)) {

return "userUpdate.jsp";

} else {

return "userView.jsp";

}

}

@RequestMapping(value = "deleteById", method = RequestMethod.GET)

@ApiOperation(value = "根据用户id删除用户信息", notes = "根据用户id删除用户信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query")

})

public String deleteById(HttpServletRequest request, HttpServletResponse response, @RequestParam(value = "id") Integer id) {

int count = 0;

try {

count = service.deleteByPrimaryKey(id);

if(count <=0 ) {

return "error.jsp";

} else {

request.getRequestDispatcher("selectAllUsers").forward(request, response);

return "userList.jsp";

}

} catch (Exception e) {

e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

@RequestMapping(value = "add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户信息", notes = "添加用户信息")

public String add(HttpServletRequest request, HttpServletResponse response, UserInfo user) {

int count = 0;

try {

count = service.insertSelective(user);

if(count <=0 ) {

return "error.jsp";

} else {

//POST请求的方法不能直接转发到GET请求的方法,需要重定向

response.sendRedirect("selectAllUsers");

return "userList.jsp";

}

} catch (Exception e) {

e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

@RequestMapping(value = "update", method = RequestMethod.POST)

@ApiOperation(value = "根据用户id修改用户信息", notes = "根据用户id修改用户信息")

public String update(HttpServletRequest request, HttpServletResponse response, UserInfo user) {

int count = 0;

try {

count = service.updateByPrimaryKeySelective(user);

if(count <=0 ) {

return "error.jsp";

} else {

//POST请求的方法不能直接转发到GET请求的方法,需要重定向

response.sendRedirect("selectAllUsers");

return "userList.jsp";

}

} catch (Exception e) {

澳门新萄京官方网站,e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

}

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiParamImplicitL:一个请求参数
  • @ApiParamsImplicit 多个请求参数

5、启动程序访问 http://localhost:8080/spring-mvc/swagger-ui.html

6、替换默认的UI

<dependency>

<groupId>com.github.xiaoymin</groupId>

<artifactId>swagger-bootstrap-ui</artifactId>

<version>1.6</version>

</dependency>

<!-- 使用swagger-bootstrap-ui替换默认的UI

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

-->

替换后访问路径:http://localhost:8080/web/doc.html

参考资料

http://blog.csdn.net/songanling/article/details/71079304

https://gitee.com/xiaoym/swagger-bootstrap-ui

源码下载地址:

本文由澳门新萄京官方网站发布于www.8455.com,转载请注明出处:澳门新萄京官方网站:Swagger2在SpringBoot环境下的

关键词: