1、swagger2的理解
引言:为什么有swagger2?
传统的项目文档都是自己手动写的文档,但是,软件是会更新变化的,文档的更新会导致一个API接口的信息不能够及时更新,导致信息流传不是很友好。Swaggers就是将注解写在对应的API方法上,当程序改变的时候,就会将对应的API改变(这个在网页的 XXXXX-swagger2-ui.html上面,那么前后端就可以根据这个进行交流就好了,不会造成交流不及时之类的问题)
swagger2可以说就是一个模版了,只不过是用于 展示API功能和详细信息的模版。网页的样式是制定好了的,需要做的就是将特定的参数填到里面去。该模版还可以展示各种测试的结果,只需要将对应的参数填进去(相当于 前端 的数据),就会有访问的 网页路径,以及 访问的结果。
应用过程:
建立一个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();
}
}
然后,就在对应的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://blog.didispace.com/springbootswagger2/
2、@RestController 和 @Controller的区别
@RestController是 @Controller和@ResponseBody 的结合体,返回的时候JSON数据,不返回 页面!!
@Controller返回的是页面!
实战是使你明白理论的最好的方法!!!!