spring boot : 集成swagger2 (REST详细设计文档)

1.     添加依赖

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

2.     创建swagger2配置类

package com.svw.tbox.tcloud.user.provider;   import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;   @Configuration @EnableSwagger2 publicclass Swagger2 {     /**      * 通过createRestApi函数创建Docket的Bean之后，      * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。      * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，      * 本例采用指定扫描的包路径来定义，      * Swagger会扫描该包下所有Controller定义的API，      * 并产生文档内容（除了被@ApiIgnore指定的请求）。      *      * @return      */     @Bean     public Docket createRestApi() {         returnnew Docket(DocumentationType.SWAGGER_2)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.svw.tbox.tcloud.user.provider.controller"))                 .paths(PathSelectors.any())                 .build();     }       /**      * 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）      *      * @return      */     private ApiInfo apiInfo() {         returnnew ApiInfoBuilder()                 .title("micro SERVICE RESTful-APIs")                 .description("Restful-API文档,POST添加,GET获取,PUT修改,DELETE删除") //                .termsOfServiceUrl("http://localhost:8000/swagger-ui.html") //请求swagger-ui.html                 .contact(new Contact("developers","", "1637761016@qq.com"))                 .version("1.0")                 .build();     } }

此处已经完成了集成，可以访问运行http://localhost:8000/swagger-ui.html查看

3.     添加Controller

package com.svw.tbox.tcloud.user.provider.controller;   import org.apache.commons.lang.StringUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController;   import com.svw.tbox.tcloud.common.rule.RuleManager; import com.svw.tbox.tcloud.common.vo.PageRequest; import com.svw.tbox.tcloud.common.web.Result; import com.svw.tbox.tcloud.user.provider.entity.UserEntity; import com.svw.tbox.tcloud.user.provider.rule.AccountRule; import com.svw.tbox.tcloud.user.provider.service.UserService; import com.svw.tbox.tcloud.user.provider.vo.UserVO;   import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation;   /**  *  * @author hurf  *  * Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，使用注解@ApiIgnore隐藏方法；  */ @RestController @Api(description= "用户服务接口") publicclass UserController {       privatefinal Logger log = LoggerFactory.getLogger(this.getClass());       @Autowired     UserService userService;       /**      *  注解@ApiOperation、@ApiImplicitParams、@ApiImplicitParam为API说明；      *  paramType:查询参数类型 ,query:直接跟参数完成自动映射赋值; path以地址的形式提交数据;      *  body:流形式提交（POST）;header:参数在request headers 里边提交;form:以form表单的形式提交仅支持POST      *  @PathVariable获得请求url中的动态参数      */     @ApiOperation(value = "新增用户")     @ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", required = true),             @ApiImplicitParam(name = "age", value = "年龄（岁）", paramType = "query", required = true),             @ApiImplicitParam(name = "sex", value = "性别：（1-男 0-女）", paramType = "query", required = true),             @ApiImplicitParam(name = "grade", value = "级别：（1~10）", paramType = "query", required = true) })     @RequestMapping(value = "/users", method = RequestMethod.POST)     public Result add(String userName, intage, intsex, String grade) {         UserEntity userEntity = new UserEntity();         userEntity.setName(userName);         userEntity.setAge(age);         userEntity.setSex(age == 1 ? true : false);         userEntity.setGrade(grade);         return Result.ok(userService.add(userEntity));       }       @ApiOperation("根据id单个查询用户")     @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true)     @RequestMapping(value = "/users/{id}", method = RequestMethod.GET)     public Result findUserById(@PathVariable("id") Long id) {         return Result.ok(userService.getUserById(id));     }       @ApiOperation("修改用户")     @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true),             @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", required = true),             @ApiImplicitParam(name = "age", value = "年龄（岁）", paramType = "query", required = true),             @ApiImplicitParam(name = "sex", value = "性别：（1-男 0-女）", paramType = "query", required = true),             @ApiImplicitParam(name = "grade", value = "级别：（1~10）", paramType = "query", required = true) })     @RequestMapping(value = "/users/{id}", method = RequestMethod.PUT)     public Result findUserByName(@PathVariable("id") Long id, String userName, intage, intsex, String grade) {         UserVO userVO = new UserVO();         userVO.setId(id);         userVO.setName(userName);         userVO.setAge(age);         userVO.setGrade(grade);         return Result.ok(userService.updateUser(userVO));       }       @ApiOperation(value = "根据用户id删除用户")     @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true)     @RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)     public Result delUser(@PathVariable("id") Long id) {         return Result.ok(userService.delUser(id));     }       @ApiOperation(value = "根据年龄查用户列表")     @ApiImplicitParams({ @ApiImplicitParam(name = "age", value = "年龄", paramType = "path", required = true),             @ApiImplicitParam(name = "pageNo", value = "当前页", paramType = "query", required = true),             @ApiImplicitParam(name = "pageSize", value = "每页记录数", paramType = "query", required = true) })     @RequestMapping(value = "/users/getByAge/{age}", method = RequestMethod.GET)     public Result findUsers(@PathVariable("age") intage, intpageNo, intpageSize) {         PageRequest page = new PageRequest(pageNo, pageSize);         return Result.ok(userService.getUsersByAge(age, page));     }       /**      *  访问路径：/users/getByName/hrf?pageNo=1&pageSize=10      */     @ApiOperation(value = "根据名称模糊查用户列表")     @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "姓名", paramType = "path", required = true),             @ApiImplicitParam(name = "pageNo", value = "当前页", paramType = "query", required = true),             @ApiImplicitParam(name = "pageSize", value = "每页记录数", paramType = "query", required = true) })     @RequestMapping(value = "/users/getByName/{name}", method = RequestMethod.GET)     public Result findUsers(@PathVariable("name") String name, intpageNo, intpageSize) {         RuleManager.invalidIf(StringUtils.isBlank(name),AccountRule.NOT_NULL_USERNAME);         log.info("info根据用户名称{}查询用列表", name);         log.debug("debug根据用户名称{}查询用列表", name);         PageRequest page = new PageRequest(pageNo, pageSize);         return Result.ok(userService.getUserByName(name, page));     } }

1.     Swagger注解说明：

·        @Api：用在类上，说明该类的作用 ·        @ApiOperation：用在方法上，说明方法的作用 ·        @ApiImplicitParams：用在方法上包含一组参数说明 ·        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 ·        paramType：参数放在哪个地方 ·        header-->请求参数的获取：@RequestHeader ·        query-->请求参数的获取：@RequestParam ·        path（用于restful接口）-->请求参数的获取：@PathVariable ·        body（不常用） ·        form（不常用） ·        name：参数名 ·        dataType：参数类型 ·        required：参数是否必须传 ·        value：参数的意思 ·        defaultValue：参数的默认值 ·        @ApiResponses：用于表示一组响应 ·        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 ·        code：数字，例如400 ·        message：信息，例如"请求参数没填好" ·        response：抛出异常的类 ·        @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候） ·        @ApiModelProperty：描述一个model的属性

其他注解参考：https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

 

4.     效果

=》启动tcloud-commons-configserver

=》启动tcloud-base-eurekaserver

=》启动tcloud-gateway-zuulserver

=》启动tcloud-user-provider

=》访问http://localhost:8200/tcloud-user-provider/swagger-ui.html 

点击user- controller可以查看暴露的接口：