前言

本文檔為轉(zhuǎn)發(fā)記錄枕面！
原文鏈接：http://www.importnew.com/29514.html

Swagger2介紹
Swagger是一款RESTful接口的文檔在線自動生成、功能測試功能框架。一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)，加上swagger-ui相速，可以有很好的呈現(xiàn)。 讓手機端 前端可以很方便的知道返回數(shù)據(jù)

image.png

SpringBoot集成
這里選用的swagger版本為：2.8.0
1.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>

2.編寫配置文件(Swagger2Config.java)
主要是添加注解@EnableSwagger2和定義Docket的bean類鲜锚。

@EnableSwagger2
@Configuration
public class SwaggerConfig {
 
    //是否開啟swagger突诬，正式環(huán)境一般是需要關(guān)閉的，可根據(jù)springboot的多環(huán)境配置進行設(shè)置
    @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/", "499452441@qq.com"))
                .version("1.0.0")
                .build();
    }
}

3.添加文檔內(nèi)容(一般上是在Controller烹棉，請求參數(shù)上進行注解攒霹，這里以上章節(jié)的

/**
 * 用戶控制層 簡單演示增刪改查及分頁
 * 新增了swagger文檔內(nèi)容 2018-07-21
 * @author oKong
 *
 */
@RestController
@RequestMapping("/user")
@Api(tags="用戶API")
public class UserController {
 
    @Autowired
    IUserService userService;
 
    @PostMapping("add")
    @ApiOperation(value="用戶新增")
    //正常業(yè)務(wù)時， 需要在user類里面進行事務(wù)控制浆洗，控制層一般不進行業(yè)務(wù)控制的催束。
    //@Transactional(rollbackFor = Exception.class)
    public Map<String,String> addUser(@Valid @RequestBody UserReq userReq){
 
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        //由于設(shè)置了主鍵策略 id可不用賦值 會自動生成
        //user.setId(0L);
        userService.insert(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "新增成功");
        //事務(wù)測試
        //System.out.println(1/0);
        return result;
    }
 
    @PostMapping("update")
    @ApiOperation(value="用戶修改")    
    public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){
 
        if(userReq.getId() == null || "".equals(userReq.getId())) {
            throw new CommonException("0000", "更新時ID不能為空");
        }
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        user.setId(Long.parseLong(userReq.getId()));        
        userService.updateById(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "更新成功");
        return result;
    }
 
    @GetMapping("/get/{id}")
    @ApiOperation(value="用戶查詢(ID)")    
    @ApiImplicitParam(name="id",value="查詢ID",required=true)
    public Map<String,Object> getUser(@PathVariable("id") String id){
        //查詢
        User user = userService.selectById(id);
        if(user == null) {
            throw new CommonException("0001", "用戶ID：" + id + "，未找到");
        }
        UserResp resp = UserResp.builder()
                .id(user.getId().toString())
                .code(user.getCode())
                .name(user.getName())
                .status(user.getStatus())
                .build();
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", resp);
        return result;
    }
 
    @GetMapping("/page")
    @ApiOperation(value="用戶查詢(分頁)")        
    public Map<String,Object> pageUser(int current, int size){
        //分頁
        Page<User> page = new Page<>(current, size);
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", userService.selectPage(page));
        return result;
    }
 
}

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {
 
    @ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
    String id;
 
    @ApiModelProperty(value="編碼",dataType="String",name="code",example="001")
    @NotBlank(message = "編碼不能為空")
    String code;
 
    @ApiModelProperty(value="名稱",dataType="String",name="name",example="oKong")
    @NotBlank(message = "名稱不能為空")
    String name;
}

Swagger訪問與使用
api首頁路徑：http://127.0.0.1:8080/swagger-ui.html
調(diào)試：點擊需要訪問的api列表伏社，點擊try it out!按鈕抠刺，即可彈出一下頁面：

image.png

image.png