SpringBoot中怎么使用swagger2構建Restful APIs

本篇文章給大家分享的是有關SpringBoot中怎么使用swagger2構建Restful APIs，小編覺得挺實用的，因此分享給大家學習，希望大家閱讀完這篇文章后可以有所收獲，話不多說，跟著小編一起來看看吧。

1. 第一步，引入對應jar包：

	<!-- 集成swagger-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.6.0</version>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.6.0</version>
	</dependency>

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<String> any() {
        return Predicates.alwaysTrue();
    }

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

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

    public static Predicate<String> ant(final String antPattern) {
        return new Predicate<String>() {
            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，小編相信有部分知識點可能是我們日常工作會見到或用到的。希望你能通過這篇文章學到更多知識。更多詳情敬請關注億速云行業資訊頻道。