Spring Boot中使用Swagger2構建API文檔

時間 2019-12-05

標籤 spring boot 使用 swagger2 swagger 構建 api 文檔欄目 Spring 简体版

原文原文鏈接

程序員都很但願別人能寫技術文檔，本身卻很不肯意寫文檔。由於接口數量繁多,而且充滿業務細節,寫文檔須要花大量的時間去處理格式排版,代碼修改後還須要同步修改文檔,常常由於項目時間緊等緣由致使文檔滯後於代碼，接口調用方的抱怨聲不絕於耳。而程序員是最擅長"偷懶"的職業了,天然會有多種多樣的自動生成文檔的插件.今天要介紹的就是Swagger.html

接下來咱們在Spring Boot中使用Swagger2構建API文檔

Swagger是一個簡單但功能強大的API表達工具。它具備地球上最大的API工具生態系統，數以千計的開發人員，使用幾乎全部的現代編程語言，都在支持和使用Swagger。使用Swagger生成API，咱們能夠獲得交互式文檔，自動生成代碼的SDK以及API的發現特性等。git

咱們先來看看具體效果:
程序員

能夠看到Swagger-Ui是以controller分類,點擊一個controller能夠看到其中的具體接口,再點擊接口就能夠看到接口的信息了,如圖:github

咱們能夠看到該接口的請求方式,返回數據信息和須要傳遞的參數.並且以上數據是自動生成的,即便代碼有一些修改,Swagger文檔也會自動同步修改.很是的方便.web

構建RESTful API

在使用Swagger2前咱們須要有一個RESTful API的項目. Spring-Boot建立RESTful API項目很是的方便和快速,這裏再也不介紹如何建立,須要的能夠參照項目代碼spring

添加Swagger2依賴

在pom.xml文件中加入如下依賴.編程

<dependency>
            <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

建立Swagger2的Java配置類

經過@Configuration註解，代表它是一個配置類，@EnableSwagger2 註解開啓swagger2。apiInfo() 方法配置一些基本的信息。createRestApi() 方法指定掃描的包會生成文檔,默認是顯示全部接口,能夠用@ApiIgnore註解標識該接口不顯示。api

/**
 * Created by Yuicon on 2017/5/20.
 * https://github.com/Yuicon
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定controller存放的目錄路徑
                .apis(RequestHandlerSelectors.basePackage("com.digag.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                 // 文檔標題
                .title("DigAg")
                // 文檔描述
                .description("https://github.com/Yuicon")
                .termsOfServiceUrl("https://github.com/Yuicon")
                .version("v1")
                .build();
    }

}

編輯文檔接口信息

先看一個例子:app

@ApiOperation(value="建立條目")
    @RequestMapping(method = RequestMethod.POST)
    public JsonResult<Entry> saveEntry(@RequestBody @ApiParam(value = "條目對象", required = true) Entry entry, HttpServletRequest request) {
        return entryService.create(entry, request);
    }

Swagger2提供了一些註解來豐富接口的信息,經常使用的有:編程語言

@ApiOperation：用在方法上，說明方法的做用