情景簡述

在開發(fā)過程中,有時候我們需要不停的測試接口,自測,或者交由測試測試接口,我們需要構(gòu)建一個文檔,都是單獨(dú)寫,太麻煩了,現(xiàn)在使用springboot集成swagger2來構(gòu)建RESTful API文檔,可以在訪問接口上,直接添加注釋就能實現(xiàn)

開發(fā)環(huán)境

先介紹一下開發(fā)環(huán)境:

• jdk版本是1.8
• springboot的版本是1.4.1
• 開發(fā)工具為 intellij idea

我們先引入swagger2的jar包,pom文件引入依賴如下:

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

使用實例

接下來,我們構(gòu)建swagger2的配置類,代碼如下:

//注解開啟 swagger2 功能
@EnableSwagger2
//注解標(biāo)示,這是一個配置類,@Configuation注解包含了@Component注解
//可以不用在使用@Component注解標(biāo)記這是個bean了,
@Configuration
public class Swagger2 {

    /**
     * 通過 createRestApi函數(shù)來構(gòu)建一個DocketBean
     * 函數(shù)名,可以隨意命名,喜歡什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//調(diào)用apiInfo方法,創(chuàng)建一個ApiInfo實例,里面是展示在文檔頁面信息內(nèi)容
                .select()
                //控制暴露出去的路徑下的實例
                //如果某個接口不想暴露,可以使用以下注解
                //@ApiIgnore 這樣,該接口就不會暴露在 swagger2 的頁面下
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
    //構(gòu)建 api文檔的詳細(xì)信息函數(shù)
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標(biāo)題
                .title("Spring Boot 測試使用 Swagger2 構(gòu)建RESTful API")
                //創(chuàng)建人
                .contact("賀小五")
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}
 
swagger2的配置類已經(jīng)配置好了,下面,我們就在主函數(shù)里面隨意寫一些接口吧
 
@SpringBootApplication(scanBasePackages = {"com"})
//該注解包含了@Controller和@ResponseBody兩個注解
@RestController
public class DemoApplication{

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    /**
    * 以下函數(shù)的注釋,不增加注解了,將在下面統(tǒng)一做描述
    */


    @ApiOperation(value = "測試post請求",notes="注意事項")
    @ApiImplicitParam(dataType = "User",name = "user",value = "用戶信息",required = true)
    @RequestMapping(value = "/testPost",method = RequestMethod.POST)
    public String testPost(@RequestBody User user){
        return "success";
    }


    @ApiOperation(value = "測試get請求",notes="注意事項")
    @ApiImplicitParam(name = "id",value = "用戶id",dataType = "String",paramType = "path")
    @RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET)
    public String testGet(@PathVariable String id){
        return id;
    }

    @ApiOperation(value = "測試組合注解",notes="注意事項")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "User",name = "user",value = "用戶信息",required = true,paramType = "body"),
            @ApiImplicitParam(dataType = "string",name = "id",value = "用戶id",required = true,paramType = "path")
    })
    @RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST)
    public User joinAnnotation(@PathVariable String id,@RequestBody User user){
        return user;
    }
    
    @ApiIgnore
    public String testIgnore(){
        return "success";
    }
}

寫好controller后,我們可以訪問以下地址:http://localhost:8080/swagger-ui.html,如果你沒引入swagger2依賴,你是訪問不了的..然后你會得到一個如下頁面

image.png

上面的頁面,就是swagger2里面的頁面,可以發(fā)現(xiàn), apiInfo里面設(shè)置的內(nèi)容在左邊展示出來了,demo-application其實就是controller的類名,右邊有三個按鈕,分別是 Show/Hide,List Opertions和Expand Operations,三個按鈕都可以打開,類下的接口,點(diǎn)擊后,會得到如下一個效果頁面:

image.png

可以發(fā)現(xiàn),展示出來了,controller下的三個接口(其實有四個,只不過有一個我們用注解忽略了,在這不展示而已..)

上面三個接口,在我們注解里面添加的,都有展示,請求方式,接口名稱,現(xiàn)在我們打開某個接口,看看具體內(nèi)容,接口內(nèi)的內(nèi)容,我不在用文字描述,我直接在截圖里面添加描述了.見諒....

image.png

image.png

我們點(diǎn)擊try it out 按鈕,就會發(fā)送請求,結(jié)果如下:

image.png

swagger官網(wǎng)地址:http://swagger.io/

重要參數(shù)

下面就是介紹,上面接口中,上面關(guān)于swagger2本人常用注解的一些描述

本人常用注解說明：

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

value: 表示接口名稱
notes: 表示接口詳細(xì)描述 

@ApiImplicitParams：用在方法上包含一組參數(shù)說明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面

paramType：參數(shù)位置
header 對應(yīng)注解：@RequestHeader
query 對應(yīng)注解：@RequestParam
path 對應(yīng)注解: @PathVariable
body 對應(yīng)注解: @RequestBody
name：參數(shù)名
dataType：參數(shù)類型
required：參數(shù)是否必須傳
value：參數(shù)的描述
defaultValue：參數(shù)的默認(rèn)值
@ApiResponses：用于表示一組響應(yīng)

@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息

code：狀態(tài)碼
message：返回自定義信息
response：拋出異常的類
@ApiIgnore: 表示該接口函數(shù)不對swagger2開放展示

注意事項

以上這些就是我測試過的注解,并沒有深究,有興趣的,可以看看其它注解,或者源碼,會比我描述的全很多,

對了,需要注意下,@ApiImplicitParam注解下的paramType屬性,會影響接口的測試,如果設(shè)置的屬性跟spring的注解對應(yīng)不上,會獲取不到參數(shù),例如:paramType=path,函數(shù)內(nèi)卻使用@RequestParam注解,這樣,可能會獲取不到傳遞進(jìn)來的參數(shù),需要按照上面進(jìn)行對應(yīng),將@RequestParam注解改為@PathVariable才能獲取到對應(yīng)的參數(shù)...