欢迎访问昆山宝鼎软件有限公司网站! 设为首页 | 网站地图 | XML | RSS订阅 | 宝鼎邮箱 | 后台管理


新闻资讯

MENU

软件开发知识

以POST类型的 昆山软件定制开发 /users请求为例

点击: 次  来源:宝鼎软件 时间:2017-07-04

原文出处: 翟永超

由于Spring Boot可以或许快速开拓、便捷陈设等特性,相信有很大一部门Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目标凡是都是由于多终端的原因,这些终端会共用许多底层业务逻辑,因此我们会抽象出这样一层来同时处事于多个移动端可能Web前端。

这样一来,我们的RESTful API就有大概要面临多个开拓人员或多个开拓团队:IOS开拓、Android开拓或是Web开拓等。为了淘汰与其他团队平时开拓期间的频繁相同本钱,软件开发,传统做法我们会建设一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

  • 由于接口浩瀚,而且细节巨大(需要思量差异的HTTP请求范例、HTTP头部信息、HTTP请求内容等),高质量地建设这份文档自己就是件很是吃力的事,下游的诉苦声不停于耳。
  • 跟着时间推移,不绝修改接话柄现的时候都必需同步修改接口文档,而文档与代码又处于两个差异的前言,除非有严格的打点机制,否则很容易导致纷歧致现象。
  • 为了办理上面这样的问题,本文将先容RESTful API的重磅好同伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC措施共同组织出强大RESTful API文档。它既可以淘汰我们建设文档的事情量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时利便的修改文档说明。别的Swagger2也提供了强大的页面测试成果来调试每个RESTful API。详细结果如下图所示:

    以POST范例的 昆山软件定制开拓 /users请求为例

    下面来详细先容,假如在Spring Boot中利用Swagger2。首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,发起先阅读
    《 Spring Boot构建一个较为巨大的RESTful APIs和单位测试 》。

    下面的内容我们会以教程样例中的Chapter3-1-1举办下面的尝试(Chpater3-1-5是我们的功效工程,亦可参考)。

    添加Swagger2依赖

    在pom.xml中插手Swagger2的依赖

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

    建设Swagger2设置类

    在Application.java同级建设Swagger2的设置类Swagger2。

    @Configuration
    @EnableSwagger2
    public class Swagger2 {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中利用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请存眷:http://blog.didispace.com/")
                    .termsOfServiceUrl("http://blog.didispace.com/")
                    .contact("措施猿DD")
                    .version("1.0")
                    .build();
        }
    }

    如上代码所示,通过@Configuration注解,让Spring来加载该类设置。再通过@EnableSwagger2注解来启用Swagger2。

    再通过createRestApi函数建设Docket的Bean之后,apiInfo()用来建设该Api的根基信息(这些根基信息会展此刻文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来节制哪些接口袒露给Swagger来揭示,本例回收指定扫描的包路径来界说,Swagger会扫描该包下所有Controller界说的API,并发生文档内容(除了被@ApiIgnore指定的请求)。

    添加文档内容

    在完成了上述设置后,其实已经可以出产文档内容,可是这样的文档主要针对请求自己,而描写主要来历于函数等定名发生,对用户并不友好,我们凡是需要本身增加一些说明来富厚文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

    @RestController
    @RequestMapping(value="/users")     // 通过这里设置使下面的映射都在/users下,可去除
    public class UserController {
        static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
        @ApiOperation(value="获取用户列表", notes="")
        @RequestMapping(value={""}, method=RequestMethod.GET)
        public List<User> getUserList() {
            List<User> r = new ArrayList<User>(users.values());
            return r;
        }
        @ApiOperation(value="建设用户", notes="按照User工具建设用户")
        @ApiImplicitParam(name = "user", value = "用户具体实体user", required = true, dataType = "User")
        @RequestMapping(value="", method=RequestMethod.POST)
        public String postUser(@RequestBody User user) {
            users.put(user.getId(), user);
            return "success";
        }
        @ApiOperation(value="获取用户具体信息", notes="按照url的id来获取用户具体信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
        @RequestMapping(value="/{id}", method=RequestMethod.GET)
        public User getUser(@PathVariable Long id) {
            return users.get(id);
        }
        @ApiOperation(value="更新用户具体信息", notes="按照url的id来指定更新工具,并按照传过来的user信息来更新用户具体信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
                @ApiImplicitParam(name = "user", value = "用户具体实体user", required = true, dataType = "User")
        })
        @RequestMapping(value="/{id}", method=RequestMethod.PUT)
        public String putUser(@PathVariable Long id, @RequestBody User user) {
            User u = users.get(id);
            u.setName(user.getName());
            u.setAge(user.getAge());
            users.put(id, u);
            return "success";
        }
        @ApiOperation(value="删除用户", notes="按照url的id来指定删除工具")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
        @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
        public String deleteUser(@PathVariable Long id) {
            users.remove(id);
            return "success";
        }
    }