#Swagger

Spring Boot
前段时间看到群里有吐槽swagger整合问题，当时没仔细看，总以为是姿势不对。 这两天正好自己升级Spring Boot版本，然后突然出现了这样的一个错误： Caused by: java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWra...

Spring Boot
这个swagger的starter已经存在四年了，记得当时做这个的时候主要是由于swagger官方并没有提供类似spring boot官方其他starter模块一样的封装。当我们要用swagger的时候，还是要写很多Java配置来启动，所以就做了这个，尽可能的把原来要写在Java中的配置都转移到配置文件中来。 一个小小的封装，也获得了2k+的Star，使用也超过了3.1k。 之前由于springfox 3.0推出了starter（之前我也写了篇博客介绍使用SpringFox 3生成Swagger文档），想着既然有了这个，那就没有花太多精力去继续更新了。 但是，一直有收到用过springfox starter的小伙伴反应还是希望可以用纯配置的方式来使用swagger，希望这个swagger可以继续升级到最新的版本。所以，下面会继续跟进这个starter，这里要特别感谢andi.lin...

Spring Boot
最近 SpringFox 3.0.0 发布了，距离上一次大版本2.9.2足足有2年多时间了。可能看到这个名字，很多读者会有点陌生。但是，只要给大家看一下这两个依赖，你就知道了！ <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> <scope>compile</scope></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>...

Spring Boot
前言通过之前的两篇关于Swagger入门以及具体使用细节的介绍之后，我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。如果您还不熟悉这块，可以先阅读： Spring Boot 2.x基础教程：使用Swagger2构建强大的API文档 Spring Boot 2.x基础教程：Swagger接口分类与各元素排序问题详解 在这两篇文章中，我们构建的文档必须通过在项目中整合swagger-ui、或使用单独部署的swagger-ui和/v2/api-docs返回的配置信息才能展现出您所构建的API文档。而有些时候，我们可能只需要提供静态文档给其他对接方的时候，我们要如何快速轻便的产生静态API文档呢？ 接下来我们就来学习一个解决该问题的工具：Swagger2Markup。 Swagger2Markup简介Swagger2Markup是Github上的一个开源项目。...

Spring Boot
之前通过Spring Boot 2.x基础教程：使用Swagger2构建强大的API文档一文，我们学习了如何使用Swagger为Spring Boot项目自动生成API文档，有不少用户留言问了关于文档内容的组织以及排序问题。所以，就特别开一篇详细说说Swagger中文档内容如何来组织以及其中各个元素如何控制前后顺序的具体配置方法。 接口的分组我们在Spring Boot中定义各个接口是以Controller作为第一级维度来进行组织的，Controller与具体接口之间的关系是一对多的关系。我们可以将同属一个模块的接口定义在一个Controller里。默认情况下，Swagger是以Controller为单位，对接口进行分组管理的。这个分组的元素在Swagger中称为Tag，但是这里的Tag与接口的关系并不是一对多的，它支持更丰富的多对多关系。 默认分组首先，我们通过一个简单的例子，来看...

Spring Boot
请求参数的校验是很多新手开发非常容易犯错，或存在较多改进点的常见场景。比较常见的问题主要表现在以下几个方面： 仅依靠前端框架解决参数校验，缺失服务端的校验。这种情况常见于需要同时开发前后端的时候，虽然程序的正常使用不会有问题，但是开发者忽略了非正常操作。比如绕过前端程序，直接模拟客户端请求，这时候就会突然在前端预设的各种限制，直击各种数据访问接口，使得我们的系统存在安全隐患。 大量地使用if/else语句嵌套实现，校验逻辑晦涩难通，不利于长期维护。 所以，针对上面的问题，建议服务端开发在实现接口的时候，对于请求参数必须要有服务端校验以保障数据安全与稳定的系统运行。同时，对于参数的校验实现需要足够优雅，要满足逻辑易读、易维护的基本特点。 接下来，我们就在本篇教程中详细说说，如何优雅地实现Spring Boot服务端的请求参数校验。 JSR-303在开始动手实践之前，我们先了解一下接...

Spring Boot
随着前后端分离架构和微服务架构的流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队：IOS开发、Android开发、Web开发甚至其他的后端服务等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法就是创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题： 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。 随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。 为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Sw...

Spring Boot
现在用Swagger来生成API文档的例子已经非常多了，今天碰到开发同事问了一个问题，帮着看了一下，主要还是配置方法的问题，所以记录一下。如果您也碰到了同样的问题，希望本文对您有用。 问题描述@ApiModelProperty注解是用来给属性标注说明、默认值、是否可以为空等配置使用的，其中有一个属性allowableValues是本文要讲的重点，从属性命名上就能知道，该属性用来配置所标注字段允许的可选值。 但是这个属性是一个String类型，我们要如何配置可选值呢？ 我们可以通过源码的注释了解到一切： public @interface ApiModelProperty { /** * Limits the acceptable values for this parameter. * <p> * There are three w...

Spring Boot
Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用，增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起，方便查看与测试。 项目地址 Github：https://github.com/dyc87112/swagger-butler Gitee：https://gitee.com/didispace/swagger-butler 快速入门该工具的时候非常简单，先通过下面几步简单入门： 第一步：构建一个基础的Spring Boot应用 如您还不知道如何创建Spring Boot应用，可以先阅读本篇入门文章 第二步：在pom.xml中引入依赖 <parent> <groupId>org.springframework.boot</groupI...

Spring Cloud
Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用，增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起，方便查看与测试。 项目地址 Github：https://github.com/dyc87112/swagger-butler Gitee：https://gitee.com/didispace/swagger-butler 使用手册快速入门该工具的时候非常简单，先通过下面几步简单入门： 第一步：构建一个基础的Spring Boot应用 如您还不知道如何创建Spring Boot应用，可以先阅读本篇入门文章 第二步：在pom.xml中引入依赖 <parent> <groupId>org.springframework.boot</gr...

Spring Cloud
有很多读者问过这样的一个问题：虽然使用Swagger可以为Spring MVC编写的接口生成了API文档，但是在微服务化之后，这些API文档都离散在各个微服务中，是否有办法将这些接口都整合到一个文档中？之前给大家的回复都只是简单的说了个思路，昨天正好又有人问起，索性就举个例子写成博文供大家参考吧。 如果您还不了解Spring Cloud Zuul和Swagger，建议优先阅读下面两篇，有一个初步的了解： Spring Cloud构建微服务架构：服务网关（基础） Spring Boot中使用Swagger2构建强大的RESTful API文档 准备工作上面说了问题的场景是在微服务化之后，所以我们需要先构建两个简单的基于Spring Cloud的微服务，命名为swagger-service-a和swagger-service-b。 下面只详细描述一个服务的构建内容，另外一个只是名...

Java
在上一篇《使用Swagger2Markup实现API文档的静态部署（一）：AsciiDoc》中，我们介绍了如何使用Swagger2Markup将Swagger文档转换成AsciiDoc，再将AsciiDoc转换成静态HTML。下面，本文将继续介绍Swagger2Markup可以转换的另外两种格式：Markdown和Confluence。 Swagger2Markup简介Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。 项目主页：https://github.com/Swagger2Markup/swagger2markup 如何使用要生成Markdown和Confluence的方式非常简单，与上一篇中的方法类似，只需要修...

Java
在阅读本文之前，您先需要了解Swagger的使用，如果您还不知道它是用来干嘛的，请先阅读《Spring Boot中使用Swagger2构建强大的RESTful API文档》一文。 前言在学会了如何使用Swagger之后，我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。但是，如前文方式构建的文档必须通过在项目中整合swagger-ui、或使用单独部署的swagger-ui和/v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。 Swagger2Markup简介Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、M...

Spring Boot
简介该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档，简化原生使用swagger2的整合代码。 源码地址 GitHub：https://github.com/dyc87112/spring-boot-starter-swagger 码云：https://gitee.com/didispace/spring-boot-starter-swagger 使用样例：https://github.com/dyc87112/swagger-starter-demo 我的博客：http://blog.didispace.com 我们社区：http://spring4all.com 小工具一枚，欢迎使用和Star支持，如使用过程中碰到问题，可以提出Issue，我会尽力完善该Starter 版本基础 Spring ...

Spring Boot
简介该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档，简化原生使用swagger2的整合代码。 GitHub：https://github.com/dyc87112/spring-boot-starter-swagger 码云：http://git.oschina.net/didispace/spring-boot-starter-swagger 博客：http://blog.didispace.com 小工具一枚，欢迎使用和Star支持，如使用过程中碰到问题，可以提出Issue，我会尽力完善该Starter 版本基础 Spring Boot：1.5.x Swagger：2.7.x 如何使用在该项目的帮助下，我们的Spring Boot可以轻松的引入swagger2，主需要做下面两个步骤： 在po...