springboot + swagger 实例代码

swagger用于定义API文档。

好处:

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

1、项目结构

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

2、pom.xml

引入了两个jar。

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.2.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.2.2</version>
    </dependency>

3、Application.java

package com.xxx.firstboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication    //same as @Configuration+@EnableAutoConfiguration+@ComponentScan
@EnableSwagger2       //启动swagger注解
public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

}

说明:

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

4、UserController.java

package com.xxx.firstboot.web;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.xxx.firstboot.domain.User;
import com.xxx.firstboot.service.UserService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@RequestMapping("/user")
@Api("userController相关api")
public class UserController {

  @Autowired
  private UserService userService;

//  @Autowired
//  private MyRedisTemplate myRedisTemplate;

  @ApiOperation("获取用户信息")
  @ApiImplicitParams({
    @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"),
    @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna")
  })
  @ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
  })
  @RequestMapping(value="/getUser",method=RequestMethod.GET)
  public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
    return userService.getUser(username,password);
  }

//  @RequestMapping("/testJedisCluster")
//  public User testJedisCluster(@RequestParam("username") String username){
//    String value = myRedisTemplate.get(MyConstants.USER_FORWARD_CACHE_PREFIX, username);
//    if(StringUtils.isBlank(value)){
//      myRedisTemplate.set(MyConstants.USER_FORWARD_CACHE_PREFIX, username, JSON.toJSONString(getUser()));
//      return null;
//    }
//    return JSON.parseObject(value, User.class);
//  }

}

说明:
1、@Api:用在类上,说明该类的作用

2、@ApiOperation:用在方法上,说明方法的作用

3、@ApiImplicitParams:用在方法上包含一组参数说明

4、@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

1、paramType:参数放在哪个地方 header-->请求参数的获取:@RequestHeader

①query-->请求参数的获取:@RequestParam

② path(用于restful接口)-->请求参数的获取:@PathVariable

③body(不常用)

④ form(不常用)

2、name:参数名

3、dataType:参数类型

4、required:参数是否必须传

5、value:参数的意思

6、defaultValue:参数的默认值

5、@ApiResponses:用于表示一组响应

6、@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

1、code:数字,例如400

2、message:信息,例如"请求参数没填好"

3、response:抛出异常的类

7、@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使

1、@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:描述一个model的属性

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

需要注意的是:

ApiImplicitParam这个注解不只是注解,还会影响运行期的程序,例子如下:

  

如果ApiImplicitParam中的phone的paramType是query的话,是无法注入到rest路径中的,而且如果是path的话,是不需要配置ApiImplicitParam的,即使配置了,其中的value="手机号"也不会在swagger-ui展示出来。

具体其他的注解,查看:https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

 测试:

启动服务,浏览器输入"http://localhost:8080/swagger-ui.html"

最上边一个红框:@Api

GET红框:method=RequestMethod.GET

右边红框:@ApiOperation

parameter红框:@ApiImplicitParams系列注解

response messages红框:@ApiResponses系列注解

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

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持我们。

(0)

相关推荐

  • spring boot整合Swagger2的示例代码

    Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 1.代码示例 1).在pom.xml文件中引入Swagger2 <dependency> <groupId>io.springfox</groupId> <artifa

  • SpringBoot和Swagger结合提高API开发效率

    现在Web开发越来越倾向于前后端分离,前端使用AngularJS,React,Vue等,部署在NodeJS上,后面采用SpringBoot发布Rest服务,前后端进行分离.这样的架构灵活且特别适合大型团队的协作开发. 那么问题来了,因为前端都是和后端通过API进行交互的,那么前后端的Rest API的接口如何进行定义和沟通呢?首先想到的应该就是Swagger. 那么什么是Swagger,Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看

  • Spring Boot集成springfox-swagger2构建restful API的方法教程

    前言 之前跟大家分享了Spring MVC集成springfox-swagger2构建restful API,简单写了如何在springmvc中集成swagger2.这边记录下在springboot中如何集成swagger2.其实使用基本相同. 方法如下: 首先还是引用相关jar包.我使用的maven,在pom.xml中引用相关依赖(原来我使用的是2.2.0的,现在使用2.4.0的): <dependency> <groupId>io.springfox</groupId&g

  • Spring Boot 整合mybatis 与 swagger2

    之前使用springMVC+spring+mybatis,总是被一些繁琐的xml配置,有时候如果配置出错,还要检查各种xml配置,偶然接触到了spring boot 后发现搭建一个web项目真的是1分钟的事情,再也不用去管那么多xml配置,简直神清气爽,不用看那么多一坨xml,下面是我把以前的一些ssm项目改成了spring boot + mybatis,相对于来说优点太明显了 1. 创建独立的Spring应用程序 2. 嵌入的Tomcat,无需部署WAR文件 3. 简化Maven配置 4. 自

  • SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)

    pom.xml增加依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <

  • springboot + swagger 实例代码

    swagger用于定义API文档. 好处: 前后端分离开发 API文档非常明确 测试的时候不需要再使用URL输入浏览器的方式来访问Controller 传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件) spring-boot与swagger的集成简单的一逼 1.项目结构 和上一节一样,没有改变. 2.pom.xml 引入了两个jar. <dependency> <groupId>io.springfox</groupId

  • SpringMVC集成Swagger实例代码

    此前写过一个关于SpringBoot集成Swagger的帖子,因为有的项目是SpringMVC的,所以也简单整理了一下,基本一致. 本例使用的是spring 4.1.6版本 1.添加POM依赖 <!-- Jackson --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <vers

  • SpringBoot集成swagger的实例代码

    Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.本文简单介绍了在项目中集成swagger的方法和一些常见问题.如果想深入分析项目源码,了解更多内容,见参考资料. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 对于

  • SpringBoot创建JSP登录页面功能实例代码

    添加JSP配置 1.pom.xml添加jsp解析引擎 <dependency> <groupId>org.apache.tomcat.embed</groupId> <artifactId>tomcat-embed-jasper</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>javax.s

  • SpringBoot Tomcat启动实例代码详解

    废话不多了,具体内容如下所示: Application configuration class: @SpringBootApplication public class ServletInitializer extends SpringBootServletInitializer { @Override protected SpringApplicationBuilder configure(SpringApplicationBuilder application) { return appli

  • SpringBoot+MyBatis简单数据访问应用的实例代码

    因为实习用的是MyBatis框架,所以写一篇关于SpringBoot整合MyBatis框架的总结. 一,Pom文件 <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:

  • springboot 中文件上传下载实例代码

    Spring Boot是由Pivotal团队提供的全新框架,其设计目的是用来简化新Spring应用的初始搭建以及开发过程.该框架使用了特定的方式来进行配置,从而使开发人员不再需要定义样板化的配置.通过这种方式,Spring Boot致力于在蓬勃发展的快速应用开发领域(rapid application development)成为领导者. Spring Boot特点 1. 创建独立的Spring应用程序 2. 嵌入的Tomcat,无需部署WAR文件 3. 简化Maven配置 4. 自动配置Spr

  • springboot 在ftl页面上使用shiro标签的实例代码

    1.首先第一步导入依赖 <dependency> <groupId>com.github.theborakompanioni</groupId> <artifactId>thymeleaf-extras-shiro</artifactId> <version>1.2.1</version> </dependency> 2.在配置shiro权限的方法内加入 @Bean public ShiroDialect sh

  • springboot hazelcast缓存中间件的实例代码

    缓存来了 在dotnet平台有自己的缓存框架,在java springboot里当然了集成了很多,而且缓存的中间件也可以进行多种选择,向 redis , hazelcast 都是分布式的缓存中间件,今天主要说一下后者的实现. 添加依赖包 dependencies { compile("org.springframework.boot:spring-boot-starter-cache") compile("com.hazelcast:hazelcast:3.7.4"

  • springboot 整合 freemarker代码实例

    这篇文章主要介绍了springboot 整合 freemarker代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 依赖 <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.1.6.RELEASE&l

随机推荐