SpringBoot整合Swagger2

今天做一個小專案時用到了Swagger2，所以寫篇隨筆來記錄一下.Swagger2的優點我就不多說了。

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. 在主啟動類的同級目錄下建立Swagger2的配置類

@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * @Description:swagger2的配置檔案，這裡可以配置swagger2的一些基本的內容，比如掃描的包等等
     */
    @Bean
    public Docket createRestApi() {

        // 為swagger新增header引數可供輸入
        ParameterBuilder userTokenHeader = new ParameterBuilder();
        ParameterBuilder userIdHeader = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        userTokenHeader.name("headerUserToken").description("userToken")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        userIdHeader.name("headerUserId").description("userId")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        pars.add(userTokenHeader.build());
        pars.add(userIdHeader.build());

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.gt.video.controller"))  //要掃描的包
                .paths(PathSelectors.any()).build()
                .globalOperationParameters(pars);
    }

    /**
     * @Description: 構建 api文件的資訊
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 設定頁面標題
                .title("使用swagger2構建短視訊後端api介面文件")
                // 設定聯絡人
                .contact(new Contact("gttttttt", "https://www.cnblogs.com/gttttttt", "[email protected]"))
                // 描述
                .description("歡迎訪問短視訊介面文件，這裡是描述資訊")
                // 定義版本號
                .version("1.0").build();
    }
}
 

3. 在Controller和pojo類上編寫註解，為了方便演示，我們這裡編寫使用者註冊的Contrller

   
   @RestController
   @Api(value = "使用者註冊和登陸的介面",tags = {"使用者註冊和登陸的Controller"})
   public class RegistLoginController {
       @Autowired
       UsersService usersService;
      @PostMapping("/regist")
      @ApiOperation(value = "使用者註冊",notes = "使用者註冊的介面")
       public R regist(@RequestBody UsersEntity users) throws Exception {
           //1.判斷使用者名稱或密碼是否為空
          if(StringUtils.isBlank(users.getUsername()) || StringUtils.isBlank(users.getPassword())){
              return R.error("使用者名稱或密碼不能為空");
          }
          //2.查詢使用者名稱是否存在
          QueryWrapper<UsersEntity> wrapper = new QueryWrapper<UsersEntity>();
          wrapper.eq("username",users.getUsername());
          UsersEntity usersEntity = usersService.getOne(wrapper);
          if(usersEntity!=null){
              return R.error("使用者名稱已經存在了,請換一個吧");
          }
          //3.將使用者資訊儲存在資料庫
          users.setId(UUID.randomUUID().toString().replaceAll("-",""));
          users.setPassword(MD5Utils.getMD5Str(users.getPassword()));
          users.setFollowCounts(0);
          users.setReceiveLikeCounts(0);
          users.setFansCounts(0);
          users.setNickname(users.getUsername());
          usersService.save(users);
   
          users.setPassword("");
          return R.ok("註冊成功").put("code",200).put("data",users);
      }
   }
   
   
   
    
   

   //這裡使用了Lombok和Mybatisplus
   @Data
   @TableName("users")
   @ApiModel(value = "使用者物件",description = "這是使用者物件")
   public class UsersEntity implements Serializable {
   	private static final long serialVersionUID = 1L;
   
   	/**
   	 * 主鍵ID
   	 */
   	@TableId
   	private String id;
   	/**
   	 * 使用者名稱
   	 */
       					//name對應欄位名，example為示例，required表示必填
   	@ApiModelProperty(value = "使用者名稱",name ="username",example = "gttttttt",required = true)
   	private String username;
   	/**
   	 * 密碼
   	 */
   	@ApiModelProperty(value = "密碼",name ="password",example = "1234567",required = true)
   	private String password;
   	/**
   	 * 使用者照片
   	 */
   	@ApiModelProperty(hidden = true)	//表示提交請求時，該欄位可以忽略不寫
   	private String faceImage;
   	/**
   	 * 使用者名稱
   	 */
   	@ApiModelProperty(hidden = true)
   	private String nickname;
   	/**
   	 * 
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer fansCounts;
   	/**
   	 * 
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer followCounts;
   	/**
   	 * $column.comments
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer receiveLikeCounts;
   
   }
   
   

   4. 在瀏覽器中輸入http://localhost:8080:/swagger-ui.html
      

響應結果:

因為篇幅有限，所以截的圖片不是很好。

5. 註解

@Api：用在請求的類上，表示對類的說明
    tags="說明該類的作用，可以在UI介面上看到的註解"
    value="該引數沒什麼意義，在UI介面上也看到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用
    value="說明方法的用途、作用" 
    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組引數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
        name：引數名
        value：引數的漢字說明、解釋
        required：引數是否必須傳
        paramType：引數放在哪個地方
            · header --> 請求引數的獲取：@RequestHeader
            · query --> 請求引數的獲取：@RequestParam
            · path（用於restful介面）--> 請求引數的獲取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：引數型別，預設String，其它值dataType="Integer"       
        defaultValue：引數的預設值

@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
        code：數字，例如400
        message：資訊，例如"請求引數沒填好"
        response：丟擲異常的類

@ApiModel：用於響應類上，表示一個返回響應資料的資訊
            （這種一般用在post建立的時候，使用@RequestBody這樣的場景，
            請求引數無法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性

本篇隨筆參考以下部落格:

swagger2註解使用教程

Swagger2--Springboot使用

萬分感謝!!!