SpringBoot中怎么使用swagger2构建RestfulAPIs

本篇文章给大家分享的是有关SpringBoot中怎么使用swagger2构建Restful APIs，小编觉得挺实用的，因此分享给大家学习，希望大家阅读完这篇文章后可以有所收获，话不多说，跟着小编一起来看看吧。

10余年的城步网站建设经验，针对设计、前端、开发、售后、文案、推广等六对一服务，响应快，48小时及时工作处理。全网整合营销推广的优势是能够根据用户设备显示端的尺寸不同，自动调整城步建站的显示方式，使网站能够适用不同显示终端，在浏览器中调整网站的宽度，无论在任何一种浏览器上浏览网站，都能展现优雅布局与设计，从而大程度地提升浏览体验。创新互联公司从事“城步网站设计”,“城步网站推广”以来，每个客户项目都认真落实执行。

1. 第一步，引入对应jar包：

	
	
		io.springfox
		springfox-swagger2
		2.6.0
	
	
		io.springfox
		springfox-swagger-ui
		2.6.0
	

2. 第二步，基本信息配置：

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 在这个配置类里面我么实例化了一个Docket对象，这个对象主要包括三个方面的信息：
     --整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。
     --指定生成API文档的包名。
     --指定生成API的路径。按路径生成API可支持四种模式，这个可以参考其源码：
     * */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zzw.bootlaunch.rest"))
                .paths(PathSelectors.regex("/rest/.*"))
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("XXX系统的API")
                .description("这是一个XXX系统的描述")
                .termsOfServiceUrl("http://127.0.0.1:8080")
                .contact("zhangsanfeng")
                .version("V1.0")
                .build();
    }
}

基础的配置是对整个API文档的描述以及一些全局性的配置，对所有接口起作用。这里涉及到两个注解：

• @Configuration是表示这是一个配置类，是JDK自带的注解，前面的文章中也已做过说明。

• @EnableSwagger2的作用是启用Swagger2相关功能。

在这个配置类里面我么实例化了一个Docket对象，这个对象主要包括三个方面的信息：

• 整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。

• 指定生成API文档的包名。

• 指定生成API的路径。按路径生成API可支持四种模式，这个可以参考其源码：

public class PathSelectors {
    private PathSelectors() {
        throw new UnsupportedOperationException();
    }

    public static Predicate any() {
        return Predicates.alwaysTrue();
    }

    public static Predicate none() {
        return Predicates.alwaysFalse();
    }

    public static Predicate regex(final String pathRegex) {
        return new Predicate() {
            public boolean apply(String input) {
                return input.matches(pathRegex);
            }
        };
    }

    public static Predicate ant(final String antPattern) {
        return new Predicate() {
            public boolean apply(String input) {
                AntPathMatcher matcher = new AntPathMatcher();
                return matcher.match(antPattern, input);
            }
        };
    }
}

从源码可以看出，Swagger总共支持任何路径都生成、任何路径都不生成以及正则匹配和ant 模式匹配四种方式。大家可能比较熟悉的是前三种，最后一种ant匹配，如果不熟悉ant的话就直接忽略吧，前三种应该足够大家在日常工作中使用了。

按照rest风格编写服务类

@Slf4j
@RestController
@RequestMapping("/rest")
public class ArticleRestController {

    @Resource
    ArticleRestService articleRestService;

    /**
     * 保存
     * */
    @RequestMapping(value="/article", method = RequestMethod.POST, produces = "application/json")
    public AjaxResponse saveArticle(@RequestBody Article article){
        log.info("saveArticle:{}",article);
        //操作数据库
        articleRestService.saveArticle(article);
        return AjaxResponse.sucess(article);
    }

    /**
     * 删除
     * */
    @RequestMapping(value="/article/{id}", method = RequestMethod.DELETE, produces = "application/json")
    public AjaxResponse delArticle(@PathVariable Long id){
        log.info("delArticle:{}", id);
        //操作数据库
        articleRestService.deleteArticle(id);
        return AjaxResponse.sucess(id);
    }

    /**
     * 更新
     * */
    @RequestMapping(value="/article/{id}", method = RequestMethod.PUT, produces = "application/json")
    public AjaxResponse updateArtice(@PathVariable Long id, @RequestBody Article article){
        log.info("updateArtice:{}",article);
        //操作数据库
        article.setId(id);
        articleRestService.updateArticle(article);
        return AjaxResponse.sucess(article);
    }

    /**
     * 获取单条记录
     * */
    @RequestMapping(value = "/article/{id}", method = RequestMethod.GET, produces = "application/json")
    public AjaxResponse getArtice(@PathVariable Long id){
        /*Article article =  Article.builder().id(22L).author("张三").content("我是内容内容....")
                .title("我是标题标题...").createTime(new Date()).build();
        log.info("getArtice:{}", article);*/

        //操作数据库
        Article article = articleRestService.getArticle(id);
        return AjaxResponse.sucess(article);
    }

3. 第三步，启动并访问

启动Spring boot，然后访问：http://127.0.0.1:8080/swagger-ui.html 即可看到如下结果：

我们还可以点进去看一下每一个具体的接口，我们这里以“POST /rest/article”这个接口为例：

可以看到，Swagger为每一个接口都生成了返回结果和请求参数的示例，并且能直接通过下面的"try it out"进行接口访问，方面大家对接口进行测试。整体上感觉Swagger还是很强大的，配置也比较简单。

三、Swagger API详细配置

不过大家看到这里肯定会有点疑问：

• 第一个问题：这个返回结果和请求参数都没有中文文字性的描述，这个可不可以配置？

• 第二个问题：这个请求参应该是直接根据对象反射出来的结果，但是不是对象的每个属性都是必传的，另外参数的值也不一定满足我们的需求，这个能否配置？

答案肯定是可以的，现在我们就来解决这两个问题，直接看配置的代码：

列表页：

可以看到，现在接口都位于Article这个tag下，并且接口后面也有了我们配置好的说明。我们再看下”POST /rest/article“这个接口的详情页：

如果我们的请求参数是一个对象，那如何配置呢？这就涉及到另外两个注解：@ApiModel和@ApiModelProperty，我们还是先看代码，然后再解释，这样更容易理解：

@ApiModel(value="article对象",description="新增&更新文章对象说明")
public class Article {
 
    @Id
    @GeneratedValue
    @ApiModelProperty(name = "id",value = "文章ID",required = false,example = "1")
    private Long id;
 
    @ApiModelProperty(name = "title",value = "文章标题",required = true,example = "测试文章标题")
    private String title;
 
    @ApiModelProperty(name = "summary",value = "文章摘要",required = true,example = "测试文章摘要")
    private String summary;
 
    @ApiModelProperty(hidden = true)
    private Date createTime;
 
    @ApiModelProperty(hidden = true)
    private Date publicTime;
 
    @ApiModelProperty(hidden = true)
    private Date updateTime;
 
    @ApiModelProperty(hidden = true)
    private Long userId;
 
    @ApiModelProperty(name = "status",value = "文章发布状态",required = true,example = "1")
    private Integer status;
 
    @ApiModelProperty(name = "type",value = "文章分类",required = true,example = "1")
    private Integer type;
}

@ApiModel是对整个类的属性的配置：

• value：类的说明

• description：详细描述

@ApiModelProperty是对具体每个字段的属性配置：

• name：字段名称

• value：字段的说明

• required：是否必须

• example：示例值

• hidden：是否显示

完成上面的配置后，我们再来看效果：

点击Try it out后，我们就可以看到返回的结果：

操作还是很方便的，相比Junit和postman，通过Swagger来测试会更加便捷，当然，Swagger的测试并不能代替单元测试，不过，在联调的时候还是有非常大的作用的。

以上就是SpringBoot中怎么使用swagger2构建Restful APIs，小编相信有部分知识点可能是我们日常工作会见到或用到的。希望你能通过这篇文章学到更多知识。更多详情敬请关注创新互联行业资讯频道。