企業級springboot落地：swagger2整合并不是那么隨便

在前后聯調時，一個高質量的接口文檔工具是必不可少的。否則就會出現前后臺人員不停的來回溝通的現象，浪費大量的時間。在大多數企業的接口文檔使用的都是swaager，可能唯一的缺陷就是ui樣式不是特別給力。但是有大量的增強性工具可以使用，如yapi，其中支持swagger導出文件的展示。

如果選擇其他接口文檔工具，可能對比swagger有缺失。請謹慎選擇。

博主在公司規定定義時，規定入參值與返回值均為實體類，不允許使用其他基本類型的封裝類型。以下使用均在此前提。這里就面臨這get請求的問題，如果有興趣可以接續往下看。

1.整合springboot

1.pom文件新增

io.springfox springfox-swagger2 2.2.2 io.springfox springfox-swagger-ui 2.2.2

2.新增config文件

@Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //controller包 .apis(RequestHandlerSelectors.basePackage("com.airboot.bootdemo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("文檔標題") .description("文檔描述") .termsOfServiceUrl("http://blog.csdn.net/saytime") .version("1.0") .build(); } }

3.application中添加注解

這里需要添加增加@EnableSwagger2注解。

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

以上步驟完成后，就可以使用了，可以訪問http://localhost:[端口]/swagger-ui.html#/

附上文件結構

2.接口使用swagger2

1.修改實體類

如果需要返回的實體類帶中文名稱需要以下配置。

@ApiModel(value="DemoVO",description="對象") public class DemoVO { private static final long serialVersionUID = -1L; /** * 城市編號 */ @ApiModelProperty(value="id",name="id") private Long id; /** * 省份編號 */ @ApiModelProperty(value="省份編號",name="省份編號") private Long provinceId; /** * 城市名稱 */ @ApiModelProperty(value="城市名稱",name="城市名稱") private String cityName; /** * 描述 */ @ApiModelProperty(value="描述",name="描述") private String description;

2.修改接口

此種方式在博主公司不允許出現。

/** * 通過參數查詢(多個入參) * * @return */ @RequestMapping(value = "/selectDemoByParas", method = RequestMethod.GET) @ApiOperation(value = "查詢城市信息", notes = "根據入參查詢城市demo(入參為Long)")//notes 描述 @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "主鍵", required = true, dataType = "Long", paramType = "path"), //required 是否必填，dataType入參類型 @ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path") }) @ApiResponses(value = { @ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 400, message = "參數格式錯誤"), @ApiResponse(code = 401, message = "登錄錯誤"), @ApiResponse(code = 404, message = "未找到地址"), @ApiResponse(code = 500, message = "服務器錯誤")} ) public List selectDemoByParas(@RequestParam("id") Long id, @RequestParam("provinceId") Long provinceId) { DemoVO inputVO = new DemoVO(); inputVO.setId(id); return demoService.selectDemoVO(inputVO); }

以上是文檔效果，同時respones class下的model和model schema可以更換返回對象樣式。

可以通過try it out測試接口 同時可以切換顯示注釋的中文名稱和json格式。

@RequestMapping(value = "/selectDemoByVo", method = RequestMethod.POST) @ApiOperation(value = "查詢城市信息", notes = "根據入參查詢城市demo") //入參是pojo有三種方法 //1.@ApiParam //2.@ApiImplicitParam(name = "demoVO", value = "入參為VO", required = false, dataType = "DemoVO") //3.@ApiImplicitParams({ //@ApiImplicitParam(name = "id", value = "主鍵", required = true, dataType = "Long", paramType = "path"), //@ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path") //}) //!!!!但是建議使用@ApiParam 這樣可以顯示出入參格式和中文名稱 如例 public List selectDemoByVo(@RequestBody @ApiParam(name = "用戶對象", value = "傳入json格式", required = true) DemoVO demoVO) { return demoService.selectDemoVO(demoVO); }

@Log(operationName = "機構部門-查詢工作組用戶") @GetMapping("/selectWorkSysUser") @ApiOperation(value = "通過實體查詢用戶", notes = "通過實體查詢用戶") public Result> selectWorkSysUser(@ApiParam(name = "入參對象", value = "實體", required = false) SysUserVO sysSysUserVO) throws TemplateException { }

以上是效果，同時respones class和parameters都可以選擇樣式。

/** * 通過List查詢 * * @param demoVO * @return */ @RequestMapping(value = "/selectDemoByList", method = RequestMethod.POST) @ApiOperation(value = "查詢城市信息", notes = "根據入參查詢城市demo") @ApiImplicitParam(name = "demoVO", value = "入參為List", required = false, dataType = "List") public List selectDemoByList(@RequestBody List demoVO) { return demoService.selectDemoVO(demoVO.get(0)); }

以上是效果，同以上相同

三 常用注解含義

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

Spring Boot

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。