您的位置:首页 > 编程语言 > Java开发

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

2018-03-12 21:53 579 查看

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表单的形式提交仅
139c8
支持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可以查看暴露的接口:

内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: