Springboot整合Swagger

Springboot整合Swagger

引言

1.传统模式我们大家之前在做项目开发的时候可能会很少接触前后端分离的项目，基本上就是前端工程师编写HTML，完成页面设计，然后在使用模板技术将写好的前端代码转化为脚本，同时也会内嵌一些后端提供的模板变量以及逻辑操作之后将代码全部打包和后端代码一起放到服务器上。
或者说更简单的方法就是先写后端逻辑代码，之后通过我们的thymeleaf模板引擎对HTML视图进行渲染，之后打包传到服务器上运行就可以了。
2.前后端分离：其实前后端分离并不只是开发模式，更是web应用的一种架构模式，在开发阶段，前后端工程师约定好数据交互接口，实现并行开发和测试；在运行阶段前后端分离模式需要对web应用进行分离部署，前端使用http或者其他协议进行交互请求。作为一种架构模式说的话，主要从四个方面进行理解：交互形式、代码组织方式、开发模式、数据接口规范流程

3.传统架构模式与前端后分离架构比较：
在传统架构中模式中，前后端代码存放于同一个代码库中，甚至是同一工程目录下，页面中还夹杂着后端代码，前后端工程师进行开始时，都必须把整个项目导入开发工具中。
在前后端分离架构中，后端只需要负责按照约定的数据格式向前端提供可调用的API服务即可，前后端之间通过HTTP协议进行交互，前端获取到数据后，进行页面的组装和渲染，最终返回给浏览器。

什么是Swagger

Swagger没有什么具体的定义，他只是一个可视化工具或者是一个规范，通过这套规范，你只需要按照他的规范去定义接口以及接口的相关信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等
具体详细可以查看swagger官网：https://swagger.io/

springboot整合Swagger

1.配置pom.xml文件（可能涉及到版本问题，自行调试）

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

2.修改Application.java启动类（加上第二行代码）

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

3.创建Swagger配置类（最好和启动类在同级目录）

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wxy.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("欢迎到我的GitHub：https://github.com/1610wang/")
                .termsOfServiceUrl("https://github.com/1610wang/")
                .contact("wxy)
                .version("1.0")
                .build();
    }
}

4.Restful接口（注解个别解释如下）
@ApiOperation：
@ApiOperation不是spring自带的注解是swagger里的
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiImplicitParam：
@ApiImplicitParam(value = “备注输入参数名称（中文）”, name = “备注输入参数名称（英文）”, required = （true、false）该入参是否必填, dataType = “（String）该入参的数据类型”, paramType = “（query）前台接口调用时url 参数形式”)
如：query 的形式：getUser?user =admin
path的形式：getUser/user/admin

@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";
    }
}

5.完成上述代码后，启动springboot程序，访问：http://localhost:8080/swagger-ui.html（注意你的端口号）


如果运行结果是如上页面，说明成功！！！

总结

总之，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。