SpringBoot集成和使用Swagger2

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

万恶的添加依赖

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

修改application.yml

增加swagger配置属性，用于配置是否启用

#配置swagger是否开启
swagger:
enabled: true

增加配置文件Swagger2Config.java

主要是添加注解@EnableSwagger2和定义Docket的bean类。

package Net.XiangCaoWuYu.Configurations;
import org.springframework.beans.factory.annotation.Value;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Value(value = "${swagger.enabled}")
boolean swaggerEnabled;
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("香草物语")
.description("香草物语")
.contact(new Contact("香草物语", "http://www.xiangcaowuyu.net", "lisen@lisen.me"))
.version("0.1").build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否开启
.enable(swaggerEnabled)
.select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("Net.XiangCaoWuYu.Api"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/*");
}
}

修改实体类

package Net.XiangCaoWuYu.Pojos;
import Net.XiangCaoWuYu.Common.Utils.HtmlUtil;
import com.fasterxml.jackson.annotation.JsonBackReference;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.extern.java.Log;
import org.springframework.format.annotation.DateTimeFormat;
import javax.persistence.*;
import javax.validation.constraints.NotBlank;
import java.io.Serializable;
import java.util.Date;
/**
* ClassName: Post <br/>
* Description: <br/>
* date: 2019/7/23 9:25<br/>
*
* @author lisen01<br />
* @since JDK 1.8
*/
@Entity
@Table(name = "posts")
@ApiModel
@Data
public class Post implements Serializable {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@Column(name = "ID")
@ApiModelProperty(name = "id", dataType = "long", value = "内码", example = "1")
@NotBlank(message = "内码不能为空")
Long id;
@Column(name = "post_author")
Long postAuthor;
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@Column(name = "post_date")
Date postDate;
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@Column(name = "post_date_gmt")
Date postDateGmt;
@Column(name = "post_content")
String postContent;
@Column(name = "post_title")
String postTitle;
@Column(name = "post_excerpt")
String postExcerpt;
@Column(name = "post_status", length = 20)
String postStatus;
@Column(name = "ping_status", length = 20)
String pingStatus;
@Column(name = "comment_status", length = 20)
String commentStatus;
@Column(name = "post_password", length = 255)
String postPassword;
@Column(name = "post_name")
String postName;
@Column(name = "to_ping")
String toPing;
@Column(name = "pinged")
String pinged;
@Column(name = "post_modified")
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
String postModified;
@Column(name = "post_modified_gmt")
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
String postModifiedGmt;
@Column(name = "post_content_filtered")
String postContentFiltered;
@Column(name = "post_parent")
Long postParent;
@Column(name = "guid")
String guid;
@Column(name = "menu_order")
int menuOrder;
@ManyToOne
@JoinColumn(name = "postType")
PostType postType;
@Column(name = "comment_count")
Long commentCount;
public String getThumnailImage() {
return HtmlUtil.getSingleImgStr(postContent);
}
@Column(insertable = false, updatable = false)
String thumnailImage;
}

修改控制器

添加文档内容(一般上是在Controller，请求参数上进行注解。

package Net.XiangCaoWuYu.Api;
import Net.XiangCaoWuYu.Pojos.Post;
import Net.XiangCaoWuYu.Services.PostService;
import com.sun.xml.internal.bind.v2.model.core.ID;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@ResponseBody
@RestController
@RequestMapping(value = "/post")
@Api(tags = "文章操作Api")
public class PostApi {
@Autowired
PostService postService;
@GetMapping("/get/{id}")
@ApiOperation("根据ID获取文章")
@ApiImplicitParam(name = "id",value = "文章ID",required = true)
public List<Post> getPost(@PathVariable long id) {
if (StringUtils.isEmpty(id)) {
return postService.getAllPosts();
} else {
List<Post> posts = new ArrayList<>();
posts.add(postService.getPostByID(id));
return posts;
}
}
;
}

Swagger访问与使用

api首页路径：http://127.0.0.1:8080/swagger-ui.html

调试：点击需要访问的api列表，点击try it out!按钮，即可弹出一下页面：

Swagger常用属性说明
作用范围 API 使用位置
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上
常用的注解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有进行标注，对于其他注解，大家可自动谷歌，毕竟常用的就这几个了。有了swagger之后，原本一些post请求需要postman这样的调试工具来进行发起，而现在直接在页面上就可以进行调试了，是不是很爽！对于服务的调用者而已，有了这份api文档也是一目了然，不需要和后端多少沟通成本，按着api说明进行前端开发即可。

历史上的今天:

2017: 吐槽一下垃圾的联通(0条评论)

本文地址：https://www.lisen.me/springboot-integration-and-use-swagger2.html
版权声明：本文为原创文章，版权归木子网所有，欢迎分享本文，转载请保留出处！