Swagger
是一款RESTful
接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful
风格的Web
服务,加上swagger-ui
,可以有很好的呈现。万恶的添加依赖
- <!--添加swagger -->
- <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
版权声明:本文为原创文章,版权归 木子网 所有,欢迎分享本文,转载请保留出处!
版权声明:本文为原创文章,版权归 木子网 所有,欢迎分享本文,转载请保留出处!