SpringBoot集成Swagger UI显示的接口可以显示Json格式的信息说明

这篇具有很好参考价值的文章主要介绍了SpringBoot集成Swagger UI显示的接口可以显示Json格式的信息说明。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

介绍

       Swagger是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
       使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
       提供 Web 页面在线测试 API,参数和格式都定好,直接在界面上输入参数对应的值即可在线测试接口。

SpringBoot集成swagger

1、导入swagger依赖

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

2、添加swagger配置

package com.jingai.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class AppConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).useDefaultResponseMessages(false)
                .apiInfo(apiInfo()).globalRequestParameters(globalRequestParameters())
                .select()
                // 此处的apis填写的包名必现是接口所在的控制类的包名
                .apis(RequestHandlerSelectors.basePackage("com.jingai.swagger.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXX服务接口").description("微服务接口文档")
                .version("1.0").build();
    }

    /**
     * 添加公用请求参数。如时间戳、签名等
     * @return
     */
    private List<RequestParameter> globalRequestParameters() {
        List<RequestParameter> list = new ArrayList<>();
        /*RequestParameterBuilder builder = new RequestParameterBuilder();
        list.add(builder.name("timestamp").description("时间戳").required(true).build());*/
        return list;
    }
}

注:创建Docket时,apis中填写的包名必现是接口所在的控制类的包名

3、在接口中添加swagger注解

package com.jingai.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

@Api(tags = "会员接口")
@RestController
public class TestController {

    @ApiOperation(value = "获取会员信息")
    @ApiImplicitParam(name = "id", dataType = "java.lang.Integer", value = "会员id", required = true)
    @ApiResponse(code = 200, message = "返回成功")
    @GetMapping("member/get")
    public Map<String, Object> getMember(@RequestParam Integer id) {
        if(id == null || id <= 0) {
            throw new IllegalArgumentException("会员id不能为空");
        }
        HashMap<String, Object> rs = new HashMap<String, Object>(4);
        rs.put("id", 1);
        rs.put("name", "张三");
        rs.put("sex", "男");
        rs.put("age", "25");
        return rs;
    }
}

项目启动之后,访问

http://localhost:8080/swagger-ui/index.html

显示效果如下:

swagger-ui response body json 转义了 中文正常显示,后端,java,测试工具

点击“获取会员信息”,显示效果如下:

swagger-ui response body json 转义了 中文正常显示,后端,java,测试工具

从以上的接口的详细信息可以发现,接口返回的信息只有状态信息,而接口返回的信息没法查看,只能通过“Try it out”进行测试方可知道。

以下为执行接口后返回的效果:

swagger-ui response body json 转义了 中文正常显示,后端,java,测试工具

swagger提供通过@ApiModel等注解来实现返回信息的查看,使用方式如下:

3.1 定义一个返回对象,添加@ApiModel、@ApiModelProperty注解

package com.jingai.swagger.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@ApiModel("会员信息")
public class MemberVo {

    @ApiModelProperty("会员id")
    private int id;

    @ApiModelProperty("名称")
    private String name;

    @ApiModelProperty("年龄")
    private int age;

    @ApiModelProperty("性别")
    private String sex;

}

3.2 在接口的@ApiResponse中添加response。在TestController.java中添加一个新的接口

    @ApiOperation(value = "获取会员信息1")
    @ApiImplicitParam(name = "id", dataType = "java.lang.Integer", value = "会员id", required = true)
    @ApiResponse(code = 200, message = "返回成功1", response = MemberVo.class)
    @GetMapping("member/get1")
    public MemberVo getMember1(@RequestParam Integer id) {
        if(id == null || id <= 0) {
            throw new IllegalArgumentException("会员id不能为空");
        }
        MemberVo memberVo = new MemberVo();
        memberVo.setId(id);
        memberVo.setAge(25);
        memberVo.setName("李四");
        memberVo.setSex("男");
        return memberVo;
    }

再次刷新

http://localhost:8080/swagger-ui/index.html

此时界面新增了member/get1接口信息,显示效果如下:

swagger-ui response body json 转义了 中文正常显示,后端,java,测试工具

使用@ApiModel比较麻烦,需要先创建一个对应的类。

那么有没有简单的方法可以实现返回任意的信息,且能够在接口中直接查看呢?

4、Swagger扩展

Swagger没有提供原生的此方面的支持,但是可以通过一些方式对Swagger进行扩展,让Swagger支持这种诉求。一起来看下如何实现吧。

Swagger的@ApiResponse中的message是支持Html5的标签的,通过测试发现,虽然可以填写普通的div、span等控件,但是无法添加css。好在Html5提供了<pre>、<code>等控件,以下的实现就是通过向前端返回一段<pre>来实现任意Json字符串返回值信息的展示。

实现的思路是:自定义注解、实现Swagger的扩展插件、在接口中添加自定义的注解、解析自定义注解的信息,拼装成json字符串,包裹在<pre>控件中

4.1 定义注解

package com.jingai.swagger.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * swagger接口返回json格式的数据说明
 */
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiRespJson {

    /** Json格式如:{id: 会员id, name: 会员名称, age: 会员年龄, speciality: [{name: 特长名称}]} */
    String jsonStr() default "";

    /** Json数据的介绍 */
    String desc() default "";

}

此处可以根据自己项目中的实际需要进行调整,例如参考Swagger原生的@ApiImplicitParams、@ApiImplicitParam,详细说明返回值的信息。

4.2 实现Swagger的扩展插件

实现OperationBuilderPlugin接口,添加了@ApiOperation的接口都会回调OperationBuilderPlugin接口的apply()方法。在该方法中解析自定义的@ApiRespJson注解,并将解析后的信息存放到返回信息中。

package com.jingai.swagger.plugin;

import com.jingai.swagger.annotation.ApiRespJson;
import com.jingai.swagger.util.JsonAnalysis;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;

import java.util.HashSet;
import java.util.Optional;
import java.util.Set;
import java.util.SortedSet;

/**
 * 解析ApiRespJson中的json字符串,添加到@ApiResponse中的message中。可以不设置@ApiResponse
 */
@Component
@Slf4j
public class ApiResponseJsonBuilderPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        final Optional<ApiRespJson> apiRespJson = context.findAnnotation(ApiRespJson.class);
        if(apiRespJson.isPresent()) {
            final ApiRespJson respJson = apiRespJson.get();
            final OperationBuilder operationBuilder = context.operationBuilder();
            operationBuilder.responses(plugResponseMessage(operationBuilder, respJson));
        }
    }

    /**
     * responseMessage增强
     * @param operationBuilder
     * @param respJson
     */
    private Set<Response> plugResponseMessage(OperationBuilder operationBuilder, ApiRespJson respJson) {
        final SortedSet<Response> responses = operationBuilder.build().getResponses();
        Set<Response> set = new HashSet<Response>(1);
        boolean addJson = false;
        for(Response res : responses) {
            if("200".equals(res.getCode())) {
                final Response resp = new ResponseBuilder().code(res.getCode())
                        .description(convertToHtml(res.getDescription(), respJson.jsonStr(), respJson.desc())).build();
                set.add(resp);
                addJson = true;
            }
        }
        if(!addJson) {
            final Response resp = new ResponseBuilder().code("200")
                    .description(convertToHtml("成功", respJson.jsonStr(), respJson.desc())).build();
            set.add(resp);
        }
        return set;
    }

    /**
     * 转换成html字符串
     * @return
     */
    private static String convertToHtml(String message, String json, String desc) {

        json = addSuccessInfo(json);

        StringBuilder sb = new StringBuilder();
        sb.append("<p><strong>").append(message).append("</strong></p>");
        sb.append("<pre>");
        if(StringUtils.hasText(desc)) {
            sb.append("<p><strong>说明:</strong>").append(desc).append("</p>");
        }
        sb.append("<code>");
        sb.append(JsonAnalysis.convert2Html(json));

        sb.append("</code></pre>");

        return sb.toString();
    }

    /**
     * 添加200成功信息
     * @param json
     * @return
     */
    private static String addSuccessInfo(String json) {
        json = json.replace(" ", "");
        final StringBuilder temp = new StringBuilder();
        temp.append("{code:200,msg:成功,data:");
        if(json.startsWith("{data:")) {
            json = json.replace("{data:", temp.toString());
        } else {
            json = temp.toString() + json + "}";
        }
        return json;
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

4.3 在接口中添加自定义的注解

在TestController.java中添加一个新的接口,添加自定义的@ApiRespJson注解

    @ApiOperation(value = "获取会员信息")
    @ApiImplicitParam(name = "id", dataType = "java.lang.Integer", value = "会员id", required = true)
    @ApiRespJson(jsonStr = "{id:会员id,name:会员名称,sex:性别,age:年龄}", desc = "介绍")
    @GetMapping("member/get2")
    public Map<String, Object> getMember2(@RequestParam Integer id) {
        if(id == null || id <= 0) {
            throw new IllegalArgumentException("会员id不能为空");
        }
        HashMap<String, Object> rs = new HashMap<String, Object>(4);
        rs.put("id", 3);
        rs.put("name", "张三");
        rs.put("sex", "男");
        rs.put("age", "25");
        return rs;
    }

重启后再次刷新Swagger的ui界面,打开member/get2,显示效果如下:

swagger-ui response body json 转义了 中文正常显示,后端,java,测试工具

总结

关于Swagger如何通过自定义方式扩展Swagger的能力使得Swagger可以返回json信息说明就分享到这里。关于本篇内容你有什么自己的想法或独到见解,欢迎在评论区一起交流探讨下吧。

 源码:https://github.com/tx917/swagger-demo文章来源地址https://www.toymoban.com/news/detail-847228.html

到了这里,关于SpringBoot集成Swagger UI显示的接口可以显示Json格式的信息说明的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • swagger 3.0.0 集成 springboot 2.6+ 生成doc.html 和swagger-ui

    1.项目中引入pom.xml依赖 特别说明: doc.html模式 swagger-bootstrap-ui只支持Swagger 2 knife4j是swagger-bootstrap-ui的升级版,支持Swagger 3。 2.创建Swagger2Config配置类 3.启动类输出文档地址 项目运行后 控制台输出log见下图 点击任意文档链接都可以进入对应的文档

    2024年02月12日
    浏览(67)
  • 关于Springboot集成swagger2出现的swagger-resouces和ui请求的404问题

    本项目集成的是增强版的Swagger文档,使用的增强版的UI com.github.xiaoymin 按照上面的配置,在本地测试效果是正常的 在红色标记的地方是正常显示的,但是按照这个配置打war包部署到服务器或者本地的tomcat中就会出现404的现象。 出现上面的这种情况时,看过很多网上的帖子说

    2024年04月17日
    浏览(36)
  • 【Spring Boot】SpringBoot 2.6.6 集成 SpringDoc 1.6.9 生成swagger接口文档

    之前常用的SpringFox在2020年停止更新了,新项目集成SpringFox出来一堆问题,所以打算使用更活跃的SpringDoc,这里简单介绍一下我这边SpringBoot2.6.6集成SpringDoc1.6.9的demo。 官网链接 maven为例: 代码如下(示例): 默认路径: UI界面 http://localhost:9527/swagger-ui/index.html json界面 http:/

    2024年02月09日
    浏览(41)
  • Springboot配置Swagger展示API文档并进行接口测试(doc.html、swagger-ui.html)

    三、创建一个测试接口 http://localhost:8080/doc.html http://localhost:8080/swagger-ui.html

    2024年02月10日
    浏览(41)
  • Springboot 2.7 集成 Swagger 增强版接口框架 Knife4j 4.3 + springdoc OpenApi 3.0

    Swagger 作为一款服务端接口文档自动生成框架,早已深入人心,并且在市场上得到了广泛的应用。然而,Swagger 3.0 也就是 OpenApi 3.0 规范发布之后便停止了更新维护,出道就是巅峰。Knife4j 作为 Swagger 的增强版,是对 Swagger UI 做了优化,同时还有很多增强的功能。伴随着 Swagge

    2024年02月08日
    浏览(47)
  • swagger-bootstrap-ui 报错No mapping for GET /doc.htm,404l,以及无法显示接口文档

    首先是访问http://ip:/doc.htmlhttp://${host}:${port}/doc.htmlhttp://ip:/doc.html报错 1、假如是SpringSecurity项目,可能是configure(WebSecurity web)没有放行,代码如下 在启动类中修改成如下代码 Swagger配置类 Controller类  Swagger依赖

    2024年02月13日
    浏览(44)
  • springboot 集成log4j日志,需要自定义json格式内容输出方便ES采集

    公司需要将服务迁移到K8S环境上,由于目前服务输出的格式不符合ES进行采集的日志格式,所有需要将日志输出的格式进行调整为JSON格式,方便ES采集 之前是直接配置的输出格式的message为 \\\"message\\\": %msg\\\" ,但是由于打日志需要打印json内容的日志就没有进行转义导致,整体输出

    2024年02月12日
    浏览(42)
  • Java技术-接口文档-Swagger2&Swagger3&接口文档UI整合

    目录 一、Swagger2完整用法 1.POM依赖 2.接口类 3.实现类 4.托管静态资源 5.接口文档配置 6.生产环境关闭接口文档 7.Swagger3页面效果 二、Swagger3完整用法 三、Swagger整合Knife4jUi 1.POM依赖 2.接口类 3.实现类 4.托管静态资源 5.接口文档配置 6.生产环境关闭接口文档 四、注释和参数讲解

    2024年02月16日
    浏览(49)
  • SpringBoot集成 Swagger

    1、Swagger 简介 1.1 解决的问题 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口,所以 API 文档变成了前后端开 发人员联系的纽带,变得越

    2024年02月15日
    浏览(41)
  • 【Springboot】集成Swagger

    启动项目后 在浏览器中输入地址 localhost:端口号/swagger-ui/ https://mp.csdn.net/mp_blog/creation/editor/132917702

    2024年02月06日
    浏览(37)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包