学习springboot小笔记（二）--swagger2的介绍以及使用

1、swagger2的理解

引言：为什么有swagger2？

传统的项目文档都是自己手动写的文档，但是，软件是会更新变化的，文档的更新会导致一个API接口的信息不能够及时更新，导致信息流传不是很友好。Swaggers就是将注解写在对应的API方法上，当程序改变的时候，就会将对应的API改变（这个在网页的 XXXXX-swagger2-ui.html上面，那么前后端就可以根据这个进行交流就好了，不会造成交流不及时之类的问题）

     swagger2可以说就是一个模版了，只不过是用于 展示API功能和详细信息的模版。网页的样式是制定好了的，需要做的就是将特定的参数填到里面去。该模版还可以展示各种测试的结果，只需要将对应的参数填进去（相当于 前端 的数据），就会有访问的 网页路径，以及 访问的结果。

应用过程：

（1）、引入依赖：

<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）、建立一个Swagger2的类：

package com.zhang;

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 {

    //API配置实现的类
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhang.web"))
                        .paths(PathSelectors.any())
                        .build();
    }

    //首页的一些 说明信息 在这边写好
    private ApiInfo apiInfo()
    {
        return new ApiInfoBuilder()
                .title("zhang22")
                .description("more to attention33")
                .termsOfServiceUrl("baidu.com44")   //该参数 体现 在哪里呢？
                .contact("zhangjifa55")
                .version("1.0.066")
                .build();
    }
}

（3）、在对应的API方法上面写上对应的注解

package com.zhang.web;

import com.zhang.domain.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@RestController
@RequestMapping(value="/users")
public class UserController {

    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表66666", notes="")
    @RequestMapping(value={""}, method=RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    @ApiOperation(value="创建用户4444", notes="根据User对象创建用户777")
    @ApiImplicitParam(name = "user333", value = "用户详细实体user222", 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", paramType = "path")
    @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", paramType = "path"),
            @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用于方法，表示一个http请求的操作，有描述的 value ，以及提示内容的 notes
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    //ApiImplicitParam用于方法，表示 单独的 请求参数。
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

//主要是这两个注解的使用
 //ApiImplicitParam用于方法，表示 单独的 请求参数。
 //ApiOperation用于方法，表示一个http请求的操作，有描述的 value ，以及提示内容的 notes

运行后打开：http://127.0.0.1:8080/swagger-ui.html 即可

注：代码参考来源：  http://blog.didispace.com/springbootswagger2/

2、@RestController 和 @Controller的区别
    @RestController是 @Controller和@ResponseBody 的结合体，返回的时候JSON数据，不返回 页面！！
    @Controller返回的是页面！

 

 

实战是使你明白理论的最好的方法！！

项目代码：https://download.csdn.net/download/zhang_li_ke/10578914