Swagger2使用記錄

1. Swagger2使用記錄

1.1. Bean配置文件

@Configuration
public class Swagger2 {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.beikbank.fund"))
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("springboot利用swagger構建api文檔")
				.description("簡單優雅的restfun風格")
//				.termsOfServiceUrl("http://www.baidu.com")
				.version("1.0")
				.build();
	}
}

@SpringBootApplication
@EnableSwagger2
public class FundApplication {

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

}

1.2. pom文件配置

 		<!-- swagger2 -->
        <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>

1.3. Bean對象屬性配置

@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@TableName("t_uls_daily_price")
@ApiModel(value="DailyPrice對象", description="每日實時統計價格")
public class DailyPrice extends Model {

    private static final long serialVersionUID = 1L;

    @TableId(value = "fund_id", type = IdType.INPUT)
    private Long fundId;

    @ApiModelProperty(value = "開盤價")
    private BigDecimal openPrice;

    @ApiModelProperty(value = "當前價格")
    private BigDecimal currPrice;

    @ApiModelProperty(value = "當前時間")
    private Date currTime;

    @ApiModelProperty(value = "創建時間")
    @TableField(fill = FieldFill.INSERT)
    private Date createTime;

    @ApiModelProperty(value = "更新時間")
    private Date updateTime;

    @ApiModelProperty(value = "狀態:0可用，1不可用")
    private transient Integer status;

    /**
     * 添加transient會導致邏輯刪除模式失效
     */
    @ApiModelProperty(value = "是否刪除：0-正常 1-軟刪除")
    @TableLogic
    @TableField(select = false)
    private Integer delFlag;


}

1. 在頁面上會顯示如下

1.4. controller配置

@RestController
@RequestMapping("/fund/daily-price")
public class DailyPriceController {

    @ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
    @ApiImplicitParam(name = "price", value = "價格", required = true, dataType = "BigDecimal", paramType = "path")
    @RequestMapping(value = "/daily/{price}", method = RequestMethod.GET)
    public ResponseEntity<DailyPrice> getUserById (@PathVariable(value = "price") BigDecimal price){
        DailyPrice r = new DailyPrice();
        r.setDailyPriceId(9999L);
        r.setCurrPrice(price);
        return ResponseEntity.ok(r);
    }
}

頁面顯示如下

1.5. swagger管理頁面訪問

1. 地址http://localhost:8080/swagger-ui.html
2. 樣式如下
   

1.6. 參數作用記錄

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

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

@ApiImplicitParams：用在請求的方法上，表示一組參數說明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面
name：參數名
value：參數的漢字說明、解釋
required：參數是否必須傳
paramType：參數放在哪個地方
· header --> 請求參數的獲取：

@ApiResponses：用在請求的方法上，表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
code：數字，例如400message：信息，例如"請求參數沒填好"response：拋出異常的類

@ApiModel：用於響應類上，表示一個返回響應數據的信息
（這種一般用在post創建的時候，使用@RequestBody這樣的場景，
請求參數無法使用@ApiImplicitParam注解進行描述的時候）

@ApiModelProperty：用在屬性上，描述響應類的屬性

概述

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：一個請求參數
@ApiImplicitParams：多個請求參數