欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

RESTful API的灵魂伴侣——Swagger

程序员文章站 2022-06-17 11:32:46
...

开篇总是要写一些概括性的东西!

 

    Swagger 是一个RESTful接口的文档的实时生成与测试工具。没接触过类似工具的你可能对这句话没什么概念,不要急,我来慢慢解释。

    使用REST的原因之一就是方便前后端分离开发,后端开发者写后端的逻辑,前端开发者写前端的逻辑,然后大家约定好一个API的风格,使用HTTP的get、post、put、delete来对应资源的CURD。避免了这种情况的发生:前端开发者拿着后端提供的厚厚的API文档边查阅边愤愤地开发,每个业务逻辑对应一个接口规范,混乱不堪。然后某一天后端改了逻辑,删掉了几个接口又增加了几个接口,前端又要大范围地改代码,然后前后端就打起来了。

    为了避免打架,规范了API的设计,使用了较为轻便的RESTful风格。而Swagger起到一个锦上添花的作用,它使得前后端的协同变得更加效率。后端开发者在定义好接口后,Swagger会自动生成并更新文档,文档中会详细记录接口的使用方法,需要传入哪些参数,又会返回什么样的结果,即节约了写文档的时间,又提高了文档的同步速度,提高了开发效率。另外Swagger不止这些功能,它还有一个强大的功能,就是在文档中直接对接口进行测试,我们可以使用Swagger模拟用户的真实操作,向后台发一个请求来验证接口是否满足需求。说了这么多,可能你还是不太明白,那我直接贴张图片吧,下图就是Swagger生成的文档:

 

 

 

 

 

    算了,不截图了,直接给个链接吧:http://petstore.swagger.io/?_ga=2.151670393.1145939008.1514200525-1067691787.1514200525

    这是官方提供一个demo文档,可以简单操作一下,聪明的你应该豁然开朗了吧!

 

    好了,Swagger介绍完了,相信大家已经认识他了吧。下面我将介绍如何在spring mvc项目中嵌入Swagger:

    本文使用 springfox-swagger实现Swagger的集成。很简单,仅仅几步就可搞定!

步骤↓:

  1. 引入jar包,此处笔者使用maven,直接引入依赖:
    		<!-- swagger RestfulAPI 文档工具 -->
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>${springfox.version}</version>
    		</dependency>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>${springfox.version}</version>
    		</dependency>
     此处使用的版本是springfox.version=2.6.1
  2. 重写一下Swagger的配置类并声明成bean:
    package com.ds.core.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.ComponentScan;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.EnableWebMvc;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    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;
    
    @EnableWebMvc
    @EnableSwagger2
    @ComponentScan("com.ds.literary.controller")//配置Swagger要扫描的包
    @Configuration
    public class SwaggerConfig extends WebMvcConfigurationSupport {
    
    	@Bean
    	public Docket docket() {
    		return new Docket(DocumentationType.SWAGGER_2)
    				.apiInfo(apiInfo())
    				.groupName("Du")
    				.select()
    //				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
    //				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
    				.paths(PathSelectors.any())
    				.build();
    	}
    
    //	@Bean
    //	public Docket xxx() {
    //		return new Docket(DocumentationType.SWAGGER_2)
    //				.apiInfo(apiInfo())
    //				.groupName("xxx")
    //				.select()
    //				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
    //				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
    //				.paths(PathSelectors.ant("/xxx/**"))
    //				.build();
    //	}
    
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder()
    				.title("Ds")
    				.contact(new Contact("Du", "", "981040863@qq.com"))
    				.version("0.0.1")
    				.build();
    	}
    }
     
  3. 在写controller的时候加入一些annotation就好了:
    @RestController
    @RequestMapping("/blog")
    @Api(value = "管理用户发表的博客,文章,日志接口", description = "管理用户发表的博客,文章,日志接口")
    public class BlogController extends BaseController<Blog>{
    	public String getService() {
    		return "blogService";
    	}
    
    	@PutMapping
    	@ApiOperation(value = "修改用户发表的博客,文章,日志", produces = MediaType.APPLICATION_JSON_VALUE)
    	public Object update(HttpServletRequest request, @RequestBody Blog param) {
                    ModelMap modelMap = new ModelMap();
                    long authorId=getCurrUser();
                    param.setAuthorId(authorId);
    		return super.update(modelMap, param);
    	}
    
    	@DeleteMapping
    	@ApiOperation(value = "删除用户发表的博客,文章,日志", produces = MediaType.APPLICATION_JSON_VALUE)
    	public Object delete(HttpServletRequest request, @RequestBody Blog param) {
                    ModelMap modelMap = new ModelMap();
    		return super.delete(modelMap, param);
    	}
    }
     
  4. 在spring中配置一个资源重定向:
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
     
  5. 启动项目,打开默认文档界面http://localhost:8080/ds-sys-web/swagger-ui.html,这个路径根据你的实际情况修改。如果你觉得这个界面丑,是可以自己定制的,具体方法本篇就不介绍了。

下面是成功后的截图:
RESTful API的灵魂伴侣——Swagger
            
    
    博客分类: 常用技术java swaggerRESTful API前后端分离spring mvcspring fox
 

 

搞定!RESTful API的灵魂伴侣——Swagger
            
    
    博客分类: 常用技术java swaggerRESTful API前后端分离spring mvcspring fox

 

  • RESTful API的灵魂伴侣——Swagger
            
    
    博客分类: 常用技术java swaggerRESTful API前后端分离spring mvcspring fox
  • 大小: 104 KB