springboot项目配置swagger2示例详解

 更新时间:2021年09月16日 10:14:03   作者:小志的博客  
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。本文重点给大家介绍springboot项目配置swagger2示例代码详解,需要的朋友参考下吧

swagger简介

  Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。

  当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要人为的维护这个接口进行测试。

一、swagger2中常用的注解作用

注解 作用
@Api 修饰整个类,描述Controller的作用 ,表示标识这个类是swagger的资源
@ApiOperation 描述一个类的一个方法,或者说一个接口,表示一个http请求的操作
@ApiParam 用于方法的参数,表示对参数的添加元数据
@ApiModelProperty 用于方法,字段。表示对model属性的说明或者数据操作更改

二、springboot项目配置swagger2步骤

1、springboot项目的目录结构如下:

在这里插入图片描述

2、pom.xml文件引入如下配置

<!--引入web相关依赖-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--引入swagger-ui-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>

3、application.yml配置文件配置如下

server:
  port: 8001 #端口
  servlet:
    context-path: /springSecurity #配置项目名称

4、Swagger配置文件如下:

package com.xz.springsecuritydemo.config;

import com.google.common.base.Predicate;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

/**
 * @description: Swagger配置文件
 * @author: xz
 */
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {

    //注入配置文件中的项目名称
    @Value("${server.servlet.context-path}")
    private String contextPath;

    /**
     * 构建 swagger2 api 文档的详细信息函数
     * @return
     */
    private ApiInfo initApiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("springSecurity测试项目 Platform API")//大标题
                .version( "1.0.0")//版本
                .description(initContextInfo())//描述
                .contact(new Contact("xz", "https://wwwxz.blog.csdn.net/", "123456@qq.com"))//作者信息
                .license("The System Server, Version 1.0")//网站链接显示文字
                .licenseUrl("https://wwwxz.blog.csdn.net/")//网站链接
                .build();

        return apiInfo;
    }

    private String initContextInfo() {
        StringBuffer sb = new StringBuffer();
        sb.append("REST API 设计在细节上有很多自己独特的需要注意的技巧,并且对开发人员在构架设计能力上比传统 API 有着更高的要求。")
                .append("<br/>")
                .append("本文通过翔实的叙述和一系列的范例,从整体结构,到局部细节,分析和解读了为了提高易用性和高效性,REST API 设计应该注意哪些问题以及如何解决这些问题。");

        return sb.toString();
    }

    /**
     * swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
     * @return
     */
    @Bean
    public Docket restfulApi() {
        System.out.println("http://localhost:8001" + contextPath + "/swagger-ui.html");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(initApiInfo())
                .groupName("RestfulApi")
                //.genericModelSubstitutes(DeferredResult.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .pathMapping(contextPath) // base,最终调用接口后会和paths拼接在一起
                .select()
                 //加了ApiOperation注解的类,才生成接口文档
                 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                 //暴露接口地址的包路径(即此包下的类,才生成接口文档)
                .apis(RequestHandlerSelectors.basePackage("com.xz.springsecuritydemo.modules.sys.controller"))
                .paths(doFilteringRules())//自定义的过滤规则
                .build();
    }

    /**
     * 设置过滤规则
     * 这里的过滤规则支持正则匹配
     * @return
     */
    private Predicate<String> doFilteringRules() {
        return or(
                regex("/testUser.*"),
                regex("/hello.*")
        );
    }
}

5、用户实体类如下:

package com.xz.springsecuritydemo.modules.sys.entity;

import io.swagger.annotations.ApiModelProperty;
/**
 * @description: 用户实体类
 * @author: xz
 */
public class UserQueryCondition {
    private int id;
    @ApiModelProperty(value = "用户名称")
    private String name;
    private int age;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

6、控制层代码如下:

package com.xz.springsecuritydemo.modules.sys.controller;

import com.xz.springsecuritydemo.modules.sys.entity.User;
import com.xz.springsecuritydemo.modules.sys.entity.UserQueryCondition;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang.builder.ReflectionToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.*;
/**
 * @description: 控制层代码如下
 * @author: xz
 */
@Api(value = "API - UserController",description = "用户模块接口详情")
@RestController
@RequestMapping("/testUser")
public class UserController {

    /***
     *  @ApiParam 如果方法接受的是具体参数,此注解需要加到方法中的参数上
     */
    @RequestMapping(value = "/queryUserByName",method = RequestMethod.GET)
    @ApiOperation(value = "根据用户名称查询服务")
    public void queryUserByName(@ApiParam(value = "用户username") @RequestParam(name="username",required = false, defaultValue ="tom" ) String name){
        System.out.println("queryUser====="+name);
    }

    /***
     * @ApiOperation 可用在方法头上.参数的描述容器
     * @ApiModelProperty 如果方法接受的是实体,此注解需要加到实体的具体属性上
     */
    @RequestMapping(value = "/queryUserAll",method = RequestMethod.GET)
    @ApiOperation(value = "根据用户id、名称和年龄查询服务")
    public void queryUserAll(UserQueryCondition userQueryCondition){
        //利用反射工具把对象输出
        System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE));
    }

    /***
     * @ApiOperation 可用在方法头上.参数的描述容器
     */
    @PostMapping(value = "/createUser")
    @ApiOperation(value = "用户新增服务")
    public User userCreate1(@RequestBody User user){
        System.out.println(user.getName()+"----"+user.getPassword());
        user.setId(1);
        return user;
    }

    /***
     * @ApiOperation 可用在方法头上.参数的描述容器
     */
    @PutMapping("/{id:\\d+}")
    @ApiOperation(value = "用户修改服务")
    public User update(@RequestBody User user){
        System.out.println(user.getId()+"======"+user.getName()+"----"+user.getPassword());
        user.setId(1);
        return user;
    }

    /***
     * @ApiOperation 可用在方法头上.参数的描述容器
     */
    @DeleteMapping("/{id:\\d+}")
    @ApiOperation(value = "用户删除服务")
    public void delete(@PathVariable String id){
        System.out.println(id);
    }
}

7、启动项目,如下图:

在这里插入图片描述

8、启动项目后,访问 http://localhost:8001/springSecurity/swagger-ui.html,如下图:

在这里插入图片描述

9、点击user-Controller,如下图所示:

在这里插入图片描述

10、点击具体某一方法,可以看到如下信息:

在这里插入图片描述

三、示例中使用的注解解析

1、@Api注解标注在了控制层的UserController类上,如下图画红色框的位置可以看到注解生效。

在这里插入图片描述

在这里插入图片描述

2、@ApiOperation注解标注在了控制层的UserController类的方法上,如下图画红色框的位置可以看到注解生效。

在这里插入图片描述

在这里插入图片描述

3、@ApiParam注解标注在了控制层的方法参数上,如下图画红色框的位置可以看到注解生效。

在这里插入图片描述

在这里插入图片描述

4、@ApiModelProperty注解标注在了实体中的属性上,在控制层方法接收实体对象时生效,如下图画红色框的位置可以看到注解生效。

在这里插入图片描述
在这里插入图片描述
在这里插入图片描述

到此这篇关于springboot项目配置swagger2示例详解的文章就介绍到这了,更多相关springboot配置swagger2内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • Java内部类知识汇总

    Java内部类知识汇总

    在Java中,在类内部可以定义成员变量与方法,还可以在类的内部定义类.这种在类的内部定义的类称为内部类.而内部类所在的类称为外部类.
    2018-03-03
  • 使用ShardingJDBC进行数据分片以及读写分离

    使用ShardingJDBC进行数据分片以及读写分离

    ShardingJDBC是一个轻量级的Java框架,提供了数据分片、读写分离、分布式主键生成等数据访问功能,本文将给大家介绍如何使用ShardingJDBC进行数据分片以及读写分离,需要的朋友可以参考下
    2024-01-01
  • Java并发之原子性 有序性 可见性及Happen Before原则

    Java并发之原子性 有序性 可见性及Happen Before原则

    一提到happens-before原则,就让人有点“丈二和尚摸不着头脑”。这个涵盖了整个JMM中可见性原则的规则,究竟如何理解,把我个人一些理解记录下来。下面可以和小编一起学习Java 并发四个原则
    2021-09-09
  • 第一次编写Java流布局图形界面

    第一次编写Java流布局图形界面

    这篇文章主要为大家详细介绍了第一次编写Java流布局图形界面的相关代码,感兴趣的小伙伴们可以参考一下
    2016-08-08
  • springboot内置tomcat调优并发线程数解析

    springboot内置tomcat调优并发线程数解析

    这篇文章主要介绍了springboot内置tomcat调优并发线程数解析,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-12-12
  • Spring Boot 如何通过ServletRequestHandledEvent事件实现接口请求的性能监控

    Spring Boot 如何通过ServletRequestHandledEvent事件实现接口请求的性能监控

    在Spring框架中,监控接口请求的性能可以通过ServletRequestHandledEvent事件实现,这篇文章给大家介绍Spring Boot 如何通过ServletRequestHandledEvent事件实现接口请求的性能监控,感兴趣的朋友跟随小编一起看看吧
    2024-08-08
  • Java利用LocalDate类实现日历设计

    Java利用LocalDate类实现日历设计

    java中做时间处理时一般会采用java.util.Date,但是相比于Date来说,还有更好的选择--java.time.LocalDate。本文就来用LocalDate类实现日历设计,感兴趣的可以动手尝试一下
    2022-07-07
  • java中PO、VO、BO、POJO、DAO、DTO、TO、QO、Bean、conn的理解

    java中PO、VO、BO、POJO、DAO、DTO、TO、QO、Bean、conn的理解

    这篇文章主要介绍了java中PO、VO、BO、POJO、DAO、DTO、TO、QO、Bean、conn的理解,需要的朋友可以参考下
    2020-02-02
  • 基于sharding-jdbc的使用限制

    基于sharding-jdbc的使用限制

    这篇文章主要介绍了sharding-jdbc的使用限制,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-10-10
  • Java雪花算法的原理和实现方法

    Java雪花算法的原理和实现方法

    这篇文章主要介绍了Java雪花算法的原理和实现方法,雪花算法是一种分布式唯一ID生成算法,可以生成全局唯一的ID标识符,就像自然界中雪花一般没有相同的雪花,下面将详细介绍,感兴趣的可以学习一下
    2023-10-10

最新评论