springboot整合swagger2

來源:https://blog.lqdev.cn/2018/07/21/springboot/chapter-ten/

Swagger是一款RESTful接口的文檔在線自動生成、功能測試功能框架。一個規范和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務，加上swagger-ui，可以有很好的呈現。

SpringBoot集成

• pom

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

• 編寫配置文件(Swagger2Config.java)

@EnableSwagger2
@Configuration
public class SwaggerConfig {
 
    //是否開啟swagger，正式環境一般是需要關閉的，可根據springboot的多環境配置進行設置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否開啟
                .enable(swaggerEnabled).select()
                // 掃描的路徑包
                .apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
                // 指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用-demo示例")
                .description("oKong | 趔趄的猿")
                // 作者信息
                .contact(new Contact("oKong", "https://blog.lqdev.cn/", "[e-mail]"))
                .version("1.0.0")
                .build();
    }
}

設置注解

• controller

  • 類:@Api(value = "預訂業務邏輯接口", description = "預訂業務邏輯接口",tags="用戶API")
  • 方法:@ApiOperation(value = "保存預訂數據", response = 本類.class)
  • 路徑參數/{id}:@ApiImplicitParam(name="id",value="查詢ID",required=true)
  • 普通參數:@ApiParam(name = "id", value = "預訂食品信息id", required = true)

• entity

  • 類名:@ApiModel(value = "記賬憑證詳情", description = "記賬憑證詳情")
  • 類屬性:@ApiModelProperty(name = "id", value = "記賬憑證詳情ID",dataType="String",example="1020332806740959233" )

訪問:http://127.0.0.1:8080/swagger-ui.html

Swagger常用屬性說明

作用范圍	API	使用位置
對象屬性	@ApiModelProperty	用在出入參數對象的字段上
協議集描述	@Api	用於controller類上
協議描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里邊
非對象參數集	@ApiImplicitParams	用在controller的方法上
非對象參數描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里邊
描述返回對象的意義	@ApiModel	用在返回對象類上

常用的注解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有進行標注，對於其他注解，大家可自動谷歌，畢竟常用的就這幾個了。有了swagger之后，原本一些post請求需要postman這樣的調試工具來進行發起，而現在直接在頁面上就可以進行調試了，是不是很爽！對於服務的調用者而已，有了這份api文檔也是一目了然，不需要和后端多少溝通成本，按着api說明進行前端開發即可。