SpringBoot集成和使用Swagger2

原创 Laughing  2019-07-27 00:38  阅读 17 次 评论 0 条
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。

万恶的添加依赖

  1. <!--添加swagger -->  
  2.         <dependency>  
  3.             <groupId>io.springfox</groupId>  
  4.             <artifactId>springfox-swagger2</artifactId>  
  5.             <version>2.8.0</version>  
  6.         </dependency>  
  7.         <dependency>  
  8.             <groupId>io.springfox</groupId>  
  9.             <artifactId>springfox-swagger-ui</artifactId>  
  10.             <version>2.8.0</version>  
  11.         </dependency>  

修改application.yml

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

  1. #配置swagger是否开启  
  2. swagger:  
  3.   enabled: true  

增加配置文件Swagger2Config.java

主要是添加注解@EnableSwagger2和定义Docketbean类。

  1. package Net.XiangCaoWuYu.Configurations;  
  2.   
  3. import org.springframework.beans.factory.annotation.Value;  
  4. import org.springframework.context.annotation.Bean;  
  5. import org.springframework.context.annotation.Configuration;  
  6. import springfox.documentation.builders.ApiInfoBuilder;  
  7. import springfox.documentation.builders.PathSelectors;  
  8. import springfox.documentation.builders.RequestHandlerSelectors;  
  9. import springfox.documentation.service.ApiInfo;  
  10. import springfox.documentation.service.Contact;  
  11. import springfox.documentation.spi.DocumentationType;  
  12. import springfox.documentation.spring.web.plugins.Docket;  
  13. import springfox.documentation.swagger2.annotations.EnableSwagger2;  
  14.   
  15. @Configuration  
  16. @EnableSwagger2  
  17. public class Swagger2Config {  
  18.     @Value(value = "${swagger.enabled}")  
  19.     boolean swaggerEnabled;  
  20.   
  21.     private ApiInfo apiInfo() {  
  22.         return new ApiInfoBuilder().title("香草物语")  
  23.                 .description("香草物语")  
  24.                 .contact(new Contact("香草物语""http://www.xiangcaowuyu.net""lisen@lisen.me"))  
  25.                 .version("0.1").build();  
  26.     }  
  27.   
  28.     @Bean  
  29.     public Docket createRestApi() {  
  30.         return new Docket(DocumentationType.SWAGGER_2)  
  31.                 .apiInfo(apiInfo())  
  32.                 //是否开启  
  33.                 .enable(swaggerEnabled)  
  34.                 .select()  
  35.                 // 扫描的路径包  
  36.                 .apis(RequestHandlerSelectors.basePackage("Net.XiangCaoWuYu.Api"))  
  37.                 // 指定路径处理PathSelectors.any()代表所有的路径  
  38.                 .paths(PathSelectors.any()).build().pathMapping("/*");  
  39.     }  
  40. }  

修改实体类

  1. package Net.XiangCaoWuYu.Pojos;  
  2.   
  3. import Net.XiangCaoWuYu.Common.Utils.HtmlUtil;  
  4. import com.fasterxml.jackson.annotation.JsonBackReference;  
  5. import io.swagger.annotations.ApiModel;  
  6. import io.swagger.annotations.ApiModelProperty;  
  7. import lombok.Data;  
  8. import lombok.extern.java.Log;  
  9. import org.springframework.format.annotation.DateTimeFormat;  
  10.   
  11. import javax.persistence.*;  
  12. import javax.validation.constraints.NotBlank;  
  13. import java.io.Serializable;  
  14. import java.util.Date;  
  15.   
  16. /** 
  17.  * ClassName: Post <br/> 
  18.  * Description: <br/> 
  19.  * date: 2019/7/23 9:25<br/> 
  20.  * 
  21.  * @author lisen01<br /> 
  22.  * @since JDK 1.8 
  23.  */  
  24. @Entity  
  25. @Table(name = "posts")  
  26. @ApiModel  
  27. @Data  
  28. public class Post implements Serializable {  
  29.     @Id  
  30.     @GeneratedValue(strategy = GenerationType.IDENTITY)  
  31.     @Column(name = "ID")  
  32.     @ApiModelProperty(name = "id", dataType = "long", value = "内码", example = "1")  
  33.     @NotBlank(message = "内码不能为空")  
  34.     Long id;  
  35.   
  36.     @Column(name = "post_author")  
  37.     Long postAuthor;  
  38.   
  39.     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")  
  40.     @Column(name = "post_date")  
  41.     Date postDate;  
  42.   
  43.     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")  
  44.     @Column(name = "post_date_gmt")  
  45.     Date postDateGmt;  
  46.   
  47.     @Column(name = "post_content")  
  48.     String postContent;  
  49.   
  50.     @Column(name = "post_title")  
  51.     String postTitle;  
  52.   
  53.     @Column(name = "post_excerpt")  
  54.     String postExcerpt;  
  55.   
  56.     @Column(name = "post_status", length = 20)  
  57.     String postStatus;  
  58.   
  59.     @Column(name = "ping_status", length = 20)  
  60.     String pingStatus;  
  61.   
  62.     @Column(name = "comment_status", length = 20)  
  63.     String commentStatus;  
  64.   
  65.     @Column(name = "post_password", length = 255)  
  66.     String postPassword;  
  67.   
  68.     @Column(name = "post_name")  
  69.     String postName;  
  70.   
  71.     @Column(name = "to_ping")  
  72.     String toPing;  
  73.   
  74.     @Column(name = "pinged")  
  75.     String pinged;  
  76.   
  77.     @Column(name = "post_modified")  
  78.     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")  
  79.     String postModified;  
  80.   
  81.     @Column(name = "post_modified_gmt")  
  82.     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")  
  83.     String postModifiedGmt;  
  84.   
  85.     @Column(name = "post_content_filtered")  
  86.     String postContentFiltered;  
  87.   
  88.     @Column(name = "post_parent")  
  89.     Long postParent;  
  90.   
  91.     @Column(name = "guid")  
  92.     String guid;  
  93.   
  94.     @Column(name = "menu_order")  
  95.     int menuOrder;  
  96.   
  97.     @ManyToOne  
  98.     @JoinColumn(name = "postType")  
  99.     PostType postType;  
  100.   
  101.     @Column(name = "comment_count")  
  102.     Long commentCount;  
  103.   
  104.     public String getThumnailImage() {  
  105.         return HtmlUtil.getSingleImgStr(postContent);  
  106.     }  
  107.   
  108.     @Column(insertable = false, updatable = false)  
  109.     String thumnailImage;  
  110. }  

修改控制器

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

  1. package Net.XiangCaoWuYu.Api;  
  2.   
  3. import Net.XiangCaoWuYu.Pojos.Post;  
  4. import Net.XiangCaoWuYu.Services.PostService;  
  5. import com.sun.xml.internal.bind.v2.model.core.ID;  
  6. import io.swagger.annotations.Api;  
  7. import io.swagger.annotations.ApiImplicitParam;  
  8. import io.swagger.annotations.ApiOperation;  
  9. import org.springframework.beans.factory.annotation.Autowired;  
  10. import org.springframework.util.StringUtils;  
  11. import org.springframework.web.bind.annotation.*;  
  12.   
  13. import java.util.ArrayList;  
  14. import java.util.List;  
  15.   
  16. @ResponseBody  
  17. @RestController  
  18. @RequestMapping(value = "/post")  
  19. @Api(tags = "文章操作Api")  
  20. public class PostApi {  
  21.     @Autowired  
  22.     PostService postService;  
  23.   
  24.     @GetMapping("/get/{id}")  
  25.     @ApiOperation("根据ID获取文章")  
  26.     @ApiImplicitParam(name = "id",value = "文章ID",required = true)  
  27.     public List<Post> getPost(@PathVariable long id) {  
  28.         if (StringUtils.isEmpty(id)) {  
  29.             return postService.getAllPosts();  
  30.         } else {  
  31.             List<Post> posts = new ArrayList<>();  
  32.             posts.add(postService.getPostByID(id));  
  33.             return posts;  
  34.         }  
  35.     }  
  36.   
  37.     ;  
  38. }  

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说明进行前端开发即可。

历史上的今天:

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

发表评论


表情