swagger2使用

向右看齐 2022-12-22 11:28 173阅读 0赞

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

## 关于Swagger ##

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

*  Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
 *  Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
 *  Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
 *  Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

> 注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

## Spring Boot集成使用Swagger ##

### 创建Spring Boot Web工程并且引入Swagger依赖 ###

所需Swagger依赖可以在[Maven仓库][Maven] 中找查询

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

### 创建User实体类 ###

package com.example.demo.domain;
    
    /** * @author liu * @title: User * @projectName demo * @description: TODO * @date 2019/3/1821:52 */
    public class User { 
        private Long id;
        private String username;
    
        public Long getId() { 
            return id;
        }
    
        public void setId(Long id) { 
            this.id = id;
        }
    
        public String getUsername() { 
            return username;
        }
    
        public void setUsername(String username) { 
            this.username = username;
        }
    
        @Override
        public String toString() { 
            return "User{" +
                    "id=" + id +
                    ", username='" + username + '\'' +
                    '}';
        }
    }

### 在启动类目录创建Swagger2配置类 ###

package com.example.demo;
    
    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;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2  { 
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//扫描controller下的包
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("swagger2 构建APIS")
                    .version("1.0")
                    .build();
        }
    }

### 创建UserController类 ###

package com.example.demo.controller;
    
    import com.example.demo.domain.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    
    /** * @author liu * @title: HelloController * @projectName demo * @description: TODO * @date 2019/3/1821:48 */
    @RestController
    @Api(tags = "用户模块")
    @RequestMapping(value = "/user")
    public class UserController { 
        /** * 此处为了方便直接用一个Map来模拟数据库进行操作 */
        static Map<Long, User> userMap;
    
        static { 
            userMap = new HashMap<>();
            User user = new User();
            user.setId((long) 10000);
            user.setUsername("admin");
            userMap.put((long) 10000,user);
        }
    
        @ApiOperation(value = "获取用户列表")
        @RequestMapping(value = "list", method = RequestMethod.GET)
        public List<User> getUserList() { 
    
            return new ArrayList<User>(userMap.values());
        }
    
    
        @ApiOperation(value = "创建用户")
        @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", name = "id", dataType = "Long", required = true, value = "用户id", defaultValue = "10001"),
                @ApiImplicitParam(paramType = "query", name = "username", dataType = "String", required = true, value = "用户名字", defaultValue = "菜菜")
        })
        @RequestMapping(value = "", method = RequestMethod.POST)
        public String postUser(User user) { 
    
            userMap.put(user.getId(),user);
            return "添加成功";
        }
    
    
    
        @ApiOperation(value = "获取用户")
        @ApiImplicitParam(paramType = "query", required = true, name = "id", dataType = "Long", value = "用户id")
        @RequestMapping(value = "", method = RequestMethod.GET)
        public User getUser(@RequestParam("id") Long id) { 
            System.out.println(id);
            return userMap.get(id);
        }
    
    
    
        @ApiOperation(value = "更新用户")
        @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", name = "id", dataType = "Long", required = true, value = "用户id", defaultValue = "10001"),
                @ApiImplicitParam(paramType = "query", name = "username", dataType = "String", required = true, value = "用户名字", defaultValue = "菜菜")
        })
        @RequestMapping(value = "", method = RequestMethod.PUT)
        public String putUser(User user) { 
            userMap.put(user.getId(),user);
            return "更新成功";
        }
    
    
        @ApiOperation(value = "删除用户")
        @ApiImplicitParam(paramType = "query", required = true, name = "id", dataType = "Long", value = "用户id")
        @RequestMapping(value = "", method = RequestMethod.DELETE)
        public String deleteUser(@RequestParam("id") Long id) { 
            userMap.remove(id);
            return "删除成功";
        }
    }

### 测试: ###

主界面:

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-OIiqKByA-1605846268510)(/swagger2简介/1.png)\]

查询用户列表:

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-VS6WO6TG-1605846268511)(/swagger2简介/2.png)\]

创建用户:

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-PrPD5iEc-1605846268513)(/swagger2简介/3.png)\]

获取用户:

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-2aboZI7w-1605846268514)(/swagger2简介/4.png)\]

删除用户:

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-gU2p22WD-1605846268515)(/swagger2简介/5.png)\]

## 使用过程中遇到的问题 ##