Spring Boot中使用集成swagger-bootstrap-ui

简介: Spring Boot中使用集成swagger-bootstrap-ui

1.引入配置

<?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:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>learn-parent</artifactId>
        <groupId>com.liupei</groupId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
 
    <artifactId>learn-swagger</artifactId>
 
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--引入swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
 
        <!--引入swagger ui包-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>
 
    </dependencies>
 
 
</project>

2.配置config

package com.liupei.common.config;
 
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
import java.util.ArrayList;
import java.util.List;
 
/**
 * TODO
 *
 * @author liu pei
 * @version 1.0
 * @date 2020/10/16 9:14
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Configuration {
 
    /**
     * 用户中心模块
     * @return
     */
    @Bean
    public Docket sys() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("莹尾狐科学-用户中心")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.liupei.sys.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    /**
     *  投诉管理 模块
     * @return
     */
    /*
    @Bean
    public Docket createComplaintRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("投诉管理")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.liupei.sys.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    */
 
 
    private ApiInfo apiInfo() {
 
        return new ApiInfoBuilder()
                .title("莹尾狐科学 API")
                .description("莹尾狐科学做的小程序 RESTful APIs")
                .termsOfServiceUrl("http://127.0.0.1:9002/doc.html")
                .contact( new Contact("刘佩","http://127.0.0.1:9002/doc.html","3268707800@qq.com"))
                .version("1.0")
                .build();
    }
 
    /**
     * 认证配置
     * @return
     */
    private List<Parameter> parameter() {
        List<Parameter> params = new ArrayList<Parameter>();
        params.add(new ParameterBuilder().name("token")
                .description("认证令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build());
        return params;
    }
 
 
}

3.实体

package com.liupei.sys.entity;
 
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
 
import java.io.Serializable;
 
/**
 * TODO
 *
 * @author liu pei
 * @version 1.0
 * @date 2020/10/16 11:11
 */
@ApiModel(value = "用户实体",description = "提供用户信息")
public class SysUser implements Serializable {
 
    @ApiModelProperty(value = "用户ID" )
    private Integer id;
 
    @ApiModelProperty(value = "用户名")
    private String name;
 
    @ApiModelProperty(value = "邮件")
    private String email;
 
    public Integer getId() {
        return id;
    }
 
    public void setId(Integer id) {
        this.id = id;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public String getEmail() {
        return email;
    }
 
    public void setEmail(String email) {
        this.email = email;
    }
}

4.配置文件

# server
server.port=9002
server.tomcat.basedir=/.
 
#线上环境开启后屏蔽所有Swagger2的资源
#swagger.production=true
swagger.basic.enable=true
##swagger  Basic认证用户名
swagger.basic.username=liupei
##swagger Basic认证密码
swagger.basic.password=123
 
#logback
logging.config=classpath:logback-spring.xml
logging.file=D:/logs/ccb-api.log
 
 
 
 
 

----------------------------------------------------完毕--------------------------------------------------

Swagger2 最全注解说明

文章目录

1,swagger2 注解整体说明

2,@API: 请求类的说明

3,@ApiOperation: 方法的说明

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

4,@ApiResponses,@ApiResponse: 方法返回值的说明

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

1,swagger2 注解整体说明

用于 controller 类上:

注解 说明
@Api 对请求类的说明

用于方法上面 (说明参数的含义):

注解 说明
@ApiOperation 方法的说明
@ApiImplicitParams、@ApiImplicitParam 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明

用于方法上面 (返回参数或对象的说明):

注解 说明
@ApiResponses、@ApiResponse 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明

对象类:

注解 说明
@ApiModel 用在 JavaBean 类上,说明 JavaBean 的 用途
@ApiModelProperty 用在 JavaBean 类的属性上面,说明此属性的的含议

2,@API: 请求类的说明

@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.

 

  1. tags="说明该类的作用"
  2. value="该参数没什么意义, 所以不需要配置"

示例:

 

  1. @API(tags="订单模块")
  2. @Controller
  3. public class OrderController {

  4. }

@API 其它属性配置:

属性名称 备注
value url 的路径值
tags 如果设置这个值、value 的值会被覆盖
description 对 api 资源的描述
basePath        基本路径
position             如果配置多个 Api 想改变显示的顺序位置
produces 如, “application/json, application/xml”
consumes  如, “application/json, application/xml”
protocols 协议类型,如: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为 true ,将在文档中隐藏

3,@ApiOperation: 方法的说明

 

  1. @ApiOperation:"用在请求的方法上, 说明方法的作用"
  2. value="说明方法的作用"
  3. notes="方法的备注说明"

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

@ApiImplicitParams: 用在请求的方法上, 包含一组参数说明

@ApiImplicitParam: 对单个参数的说明

name: 参数名

value: 参数的汉字说明, 解释

required: 参数是否必须传

paramType: 参数放在哪个地方

. header --> 请求参数的获取:@RequestHeader

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

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

 

  1. . body(请求体)--> @RequestBody User user
  2. . form(普通表单提交)

dataType: 参数类型, 默认 String, 其它值 dataType="Integer"

defaultValue: 参数的默认值

示列:

 

  1. @API(tags="用户模块")
  2. @Controller
  3. public class UserController {
  4. @ApiOperation(value="用户登录",notes="随边说点啥")
  5. @ApiImplicitParams({
  6. @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
  7. @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
  8. @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
  9. })
  10. @PostMapping("/login")
  11. public JsonResult login(@RequestParam String mobile, @RequestParam String password,
  12. @RequestParam Integer age){
  13. //...
  14. return JsonResult.ok(map);
  15. }
  16. }

4,@ApiResponses,@ApiResponse: 方法返回值的说明

@ApiResponses: 方法返回对象的说明

@ApiResponse: 每个参数的说明

code: 数字, 例如 400

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

response: 抛出异常的类

示例:

 

  1. @API(tags="用户模块")
  2. @Controller
  3. public class UserController {
  4. @ApiOperation("获取用户信息")
  5. @ApiImplicitParams({
  6. @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户 Id")
  7. })
  8. @ApiResponses({
  9. @ApiResponse(code = 400, message = "请求参数没填好"),
  10. @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
  11. })
  12. @ResponseBody
  13. @RequestMapping("/list")
  14. public JsonResult list(@RequestParam String userId) {
  15. ...
  16. return JsonResult.ok().put("page", pageUtil);
  17. }
  18. }

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

@ApiModel: 用于 JavaBean 的类上面, 表示此 JavaBean 整体的信息

(这种一般用在 post 创建的时候, 使用 @RequestBody 这样的场景,

请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

示例:

 

  1. @ApiModel(description= "返回响应数据")
  2. public class RestMessage implements Serializable{
  3. @ApiModelProperty(value = "是否成功")
  4. private boolean success=true;
  5. @ApiModelProperty(value = "返回对象")
  6. private Object data;
  7. @ApiModelProperty(value = "错误编号")
  8. private Integer errCode;
  9. @ApiModelProperty(value = "错误信息")
  10. private String message;
  11. /* getter/setter 略 */
  12. }
相关文章
|
4月前
|
安全 Java Apache
微服务——SpringBoot使用归纳——Spring Boot中集成 Shiro——Shiro 身份和权限认证
本文介绍了 Apache Shiro 的身份认证与权限认证机制。在身份认证部分,分析了 Shiro 的认证流程,包括应用程序调用 `Subject.login(token)` 方法、SecurityManager 接管认证以及通过 Realm 进行具体的安全验证。权限认证部分阐述了权限(permission)、角色(role)和用户(user)三者的关系,其中用户可拥有多个角色,角色则对应不同的权限组合,例如普通用户仅能查看或添加信息,而管理员可执行所有操作。
151 0
|
4月前
|
安全 Java 数据安全/隐私保护
微服务——SpringBoot使用归纳——Spring Boot中集成 Shiro——Shiro 三大核心组件
本课程介绍如何在Spring Boot中集成Shiro框架,主要讲解Shiro的认证与授权功能。Shiro是一个简单易用的Java安全框架,用于认证、授权、加密和会话管理等。其核心组件包括Subject(认证主体)、SecurityManager(安全管理员)和Realm(域)。Subject负责身份认证,包含Principals(身份)和Credentials(凭证);SecurityManager是架构核心,协调内部组件运作;Realm则是连接Shiro与应用数据的桥梁,用于访问用户账户及权限信息。通过学习,您将掌握Shiro的基本原理及其在项目中的应用。
151 0
|
1月前
|
前端开发
SpringBoot2.3.1集成Knife4j接口文档
SpringBoot2.3.1集成Knife4j接口文档
134 44
|
1月前
|
缓存 安全 Java
Shiro简介及SpringBoot集成Shiro(狂神说视频简易版)
Shiro简介及SpringBoot集成Shiro(狂神说视频简易版)
92 6
|
2月前
|
缓存 Java 数据库
SpringBoot集成Ehcache缓存使用指南
以上是SpringBoot集成Ehcache缓存的基本操作指南,帮助你在实际项目中轻松实现缓存功能。当然,Ehcache还有诸多高级特性,通过学习和实践,你可以更好地发挥它的威力。
128 20
|
3月前
|
Java 开发工具 Spring
【Azure Application Insights】为Spring Boot应用集成Application Insight SDK
本文以Java Spring Boot项目为例,详细说明如何集成Azure Application Insights SDK以收集和展示日志。内容包括三步配置:1) 在`pom.xml`中添加依赖项`applicationinsights-runtime-attach`和`applicationinsights-core`;2) 在main函数中调用`ApplicationInsights.attach()`;3) 配置`applicationinsights.json`文件。同时提供问题排查建议及自定义日志方法示例,帮助用户顺利集成并使用Application Insights服务。
|
4月前
|
消息中间件 存储 Java
微服务——SpringBoot使用归纳——Spring Boot中集成ActiveMQ——ActiveMQ安装
本教程介绍ActiveMQ的安装与基本使用。首先从官网下载apache-activemq-5.15.3版本,解压后即可完成安装,非常便捷。启动时进入解压目录下的bin文件夹,根据系统选择win32或win64,运行activemq.bat启动服务。通过浏览器访问`http://127.0.0.1:8161/admin/`可进入管理界面,默认用户名密码为admin/admin。ActiveMQ支持两种消息模式:点对点(Queue)和发布/订阅(Topic)。前者确保每条消息仅被一个消费者消费,后者允许多个消费者同时接收相同消息。
108 0
微服务——SpringBoot使用归纳——Spring Boot中集成ActiveMQ——ActiveMQ安装
|
4月前
|
消息中间件 Java 微服务
微服务——SpringBoot使用归纳——Spring Boot中集成ActiveMQ——发布/订阅消息的生产和消费
本文详细讲解了Spring Boot中ActiveMQ的发布/订阅消息机制,包括消息生产和消费的具体实现方式。生产端通过`sendMessage`方法发送订阅消息,消费端则需配置`application.yml`或自定义工厂以支持topic消息监听。为解决点对点与发布/订阅消息兼容问题,可通过设置`containerFactory`实现两者共存。最后,文章还提供了测试方法及总结,帮助读者掌握ActiveMQ在异步消息处理中的应用。
137 0
|
4月前
|
消息中间件 网络协议 Java
微服务——SpringBoot使用归纳——Spring Boot中集成ActiveMQ——ActiveMQ集成
本文介绍了在 Spring Boot 中集成 ActiveMQ 的详细步骤。首先通过引入 `spring-boot-starter-activemq` 依赖并配置 `application.yml` 文件实现基本设置。接着,创建 Queue 和 Topic 消息类型,分别使用 `ActiveMQQueue` 和 `ActiveMQTopic` 类完成配置。随后,利用 `JmsMessagingTemplate` 实现消息发送功能,并通过 Controller 和监听器实现点对点消息的生产和消费。最后,通过浏览器访问测试接口验证消息传递的成功性。
121 0
|
4月前
|
JSON Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
121 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用