• springboot(十六)-swagger2


    SpringBoot整合Swagger2

    相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。

    手写Api文档的几个痛点:

    1. 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
    2. 接口返回结果不明确
    3. 不能直接在线测试接口,通常需要使用工具,比如postman
    4. 接口文档太多,不好管理

    Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。

    其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。

    添加pom依赖

    <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>

    Swagger配置类

    其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。

    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.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /**
     * @author zh
     * @ClassName cn.saytime.Swgger2
     * @Description
     * @date 2017-07-10 22:12:31
     */
    @Configuration
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restfull风格,https://www.cnblogs.com/fengyuduke")
                    .termsOfServiceUrl("https://www.cnblogs.com/fengyuduke")
                    .version("1.0")
                    .build();
        }
    }

    用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。

    启动类

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

    加上注解@EnableSwagger2 表示开启Swagger。

    import cn.saytime.bean.JsonResult;
    import cn.saytime.bean.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    import springfox.documentation.annotations.ApiIgnore;
    
    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    
    /**
     * @author zh
     * @ClassName cn.saytime.web.UserController
     * @Description
     */
    @RestController
    public class UserController {
    
        // 创建线程安全的Map
        static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
    
        /**
         * 根据ID查询用户
         * @param id
         * @return
         */
        @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
        @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
        public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
            JsonResult r = new JsonResult();
            try {
                User user = users.get(id);
                r.setResult(user);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 查询用户列表
         * @return
         */
        @ApiOperation(value="获取用户列表", notes="获取用户列表")
        @RequestMapping(value = "users", method = RequestMethod.GET)
        public ResponseEntity<JsonResult> getUserList (){
            JsonResult r = new JsonResult();
            try {
                List<User> userList = new ArrayList<User>(users.values());
                r.setResult(userList);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 添加用户
         * @param user
         * @return
         */
        @ApiOperation(value="创建用户", notes="根据User对象创建用户")
        @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        @RequestMapping(value = "user", method = RequestMethod.POST)
        public ResponseEntity<JsonResult> add (@RequestBody User user){
            JsonResult r = new JsonResult();
            try {
                users.put(user.getId(), user);
                r.setResult(user.getId());
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 根据id删除用户
         * @param id
         * @return
         */
        @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
        @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
        public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
            JsonResult r = new JsonResult();
            try {
                users.remove(id);
                r.setResult(id);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 根据id修改用户信息
         * @param user
         * @return
         */
        @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
                @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
        })
        @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
        public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
            JsonResult r = new JsonResult();
            try {
                User u = users.get(id);
                u.setUsername(user.getUsername());
                u.setAge(user.getAge());
                users.put(id, u);
                r.setResult(u);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        @ApiIgnore//使用该注解忽略这个API
        @RequestMapping(value = "/hi", method = RequestMethod.GET)
        public String  jsonTest() {
            return " hi you!";
        }
    }

    启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html

    Swagger注解

    swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

    • @Api:修饰整个类,描述Controller的作用
    • @ApiOperation:描述一个类的一个方法,或者说一个接口
    • @ApiParam:单个参数描述
    • @ApiModel:用对象来接收参数
    • @ApiProperty:用对象接收参数时,描述对象的一个字段
    • @ApiResponse:HTTP响应其中1个描述
    • @ApiResponses:HTTP响应整体描述
    • @ApiIgnore:使用该注解忽略这个API
    • @ApiError :发生错误返回的信息
    • @ApiImplicitParam:一个请求参数
    • @ApiImplicitParams:多个请求参数
  • 相关阅读:
    VS2010 枚举注释任务
    osg例子中文翻译,半机翻
    怎么愉快地添加目标位置?
    变更路线节点。妈妈,我的强迫症有救啦!
    测试必备工具之抓包神器 Charles 如何抓取 https 数据包?
    测试必备工具之最强抓包神器 Charles,你会了么?
    ‘员工拒绝加班被判赔偿公司 1.8 万元’,作为测试猿你怕了么?
    全网最全测试点总结:N95 口罩应该如何测试?
    测试角度:如何看待三星大量手机系统崩溃并数据丢失事件?
    男生 vs 女生,谁更加适合做软件测试?
  • 原文地址:https://www.cnblogs.com/fengyuduke/p/10870099.html
Copyright © 2020-2023  润新知