絲襪哥 --- swagger的使用

一、是什麼?

swagger,俗稱絲襪哥,是用來生成接口文檔的。沒有使用swagger的時候,你寫完後端接口,得自己將後端接口地址一個個地整理出來,告訴別人這個接口是幹嘛的,要傳哪些參數,正常情況下返回的參數是咋樣的,非正常情況返回的又是咋樣的。很麻煩有木有?有了絲襪哥,你只需要簡單地加上幾個註解,然後會有一個絲襪哥的ui界面,裏面就包含了接口的所有信息,灰常地方便。

二、 怎麼用?

以下操作基於springboot項目。

1. 添加依賴:

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

2. 啓動類上加註解開啓swagger相關注解:

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

3. 配置swagger:

新建一個配置類,對swagger進行配置:

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhu.demo.swagger")) // 這個包下的會被swagger掃描到
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger") // swagger-ui展示的標題
                        .description("這是一個測試springboot整合swagger的項目") // swagger-ui頁面的描述
                        .version("1.0") // api版本
                        .contact(new Contact("聯繫我","www.baidu.com","[email protected]")) // 聯繫方式
                        .license("lisence_description") // license
                        .licenseUrl("http://www.baidu.com") // license地址
                        .build());
    }
}

這個配置類對swagger做了一些基礎的配置,最重要的就是掃描路徑,即basePackage,其他都是頁面上展示的東西。配置完這個,然後啓動,訪問:localhost:端口/swagger-ui.html,就可以看到如下頁面:

4. 接口中使用swagger:

假如我現在在swagger能掃描到的包下新建如下幾個類:

@Data
public class User {
    private long userId;
    private String userName;
    private String userPassword;
    private int userAge;
}
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/{userId}")
    public String query(@PathVariable("userId") Long userId){
        User user = new User();
        user.setUserId(userId);
        user.setUserName("testName");
        user.setUserPassword("testPassword");
        user.setUserAge(18);
        return JSONObject.toJSONString(user);
    }

    @PostMapping("/addUser")
    public String add(User user){
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("status", "0");
        jsonObject.put("message", "success");
        jsonObject.put("user", user);
        return jsonObject.toJSONString();
    }
}

你重啓項目,再次訪問swagger-ui,你會發現,頁面中就已經有這兩個接口了,如下:

點擊try it out,就可以對接口進行測試了。但是,這樣看起來怪怪的,因爲沒有接口的說明,也沒有字段的說明,字段是否能爲空也沒有限制,響應示例也沒有。

5. 加controller的說明:

在UserController類上加上註解:

@Api(tags = "用戶模塊")
public class UserController {
      ……
}

加上這個之後,界面就變成這樣了:

6. 其他註解:

  • @ApiOperation("獲取用戶信息"):加在方法上,表示該接口是幹嘛的,括號裏面的是該方法的說明;

  • @ApiParam(name="userId",value="用戶id",required=true, defaultValue = "1"):加在方法參數上,說明該參數是什麼意思,是否必須,還可以設置一個默認值;

如果參數是對象,那麼怎麼搞?比如上面的add方法,參數是User對象,那麼就在user類上用如下註解:

  • @ApiModel(value="User",description="用戶對象"):加在User類上,說明這個對象是幹啥的

  • @ApiModelProperty(value="用戶名",name="userName",example="律政先鋒"):加在user類屬性上,說明這個字段是幹啥的

這樣,在接口中就會顯示這些參數的釋義了。

7. 顯示model:

我們還可以直接將整個User類暴露在接口文檔中,只需要在add方法中,加上@RequestBody,那麼在頁面中就會顯示model了。

加上配置後的代碼如下:

@RestController
@RequestMapping("/user")
@Api(tags = "用戶模塊")
public class UserController {

    @ApiOperation("獲取用戶信息") // 接口描述
    @GetMapping("/{userId}")
    public String query(@ApiParam(name="userId",value="用戶id",required=true) @PathVariable("userId") Long userId){
        User user = new User();
        user.setUserId(userId);
        user.setUserName("testName");
        user.setUserPassword("testPassword");
        user.setUserAge(18);
        return JSONObject.toJSONString(user);
    }

    @ApiOperation("新增用戶信息") // 接口描述
    @PostMapping("/addUser")
    public String add(@RequestBody User user){
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("status", "0");
        jsonObject.put("message", "success");
        jsonObject.put("user", user);
        return jsonObject.toJSONString();
    }
}
@Data
@ApiModel(value="User",description="用戶對象")
public class User {
    @ApiModelProperty(value="用戶id",name="userId",example="123")
    private long userId;
    @ApiModelProperty(value="用戶名",name="userName",example="律政先鋒")
    private String userName;
    @ApiModelProperty(value="用戶密碼",name="userPassword",example="lvzf")
    private String userPassword;
    @ApiModelProperty(value="用戶年齡",name="userAge",example="18")
    private int userAge;
}

最終效果如下:

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章