侧边栏壁纸
博主头像
Epoch

Java开发、Python爬虫、微服务、分布式、前端

  • 累计撰写 93 篇文章
  • 累计创建 110 个标签
  • 累计收到 8 条评论

目 录CONTENT

文章目录

Spring Boot整合Swagger2搭建Restful API在线文档

Epoch
2020-05-05 / 0 评论 / 0 点赞 / 298 阅读 / 1,024 字 / 正在检测是否收录...

目标:Spring Boot整合Swagger2
工具:IDEA–2020.1
学习目标:框架工具集成
本次学习的工程下载链接放到文本最后面
**注意:**本次项目基于springboot集成Mybatis基础之上的

整合Swagger2步骤:

  1. 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>
  1. 配置Swagger2
    A. 写一个配置类Swagger2 ,在类的上方加上@Configuration 注解, 表明是一个配置类,加上@EnableSwagger2 开启Swagger2 的功能。
    在配置类Swagger2 中需要注入一个Docket 的Bean , 该Bean 包含了apiInfo ,即基本API 文档的描述信息,以及包扫描的基本包名等信息。
    示例代码如下:
    @Configuration
    @EnableSwagger2
    public class Swagger2 {
        @Bean
        public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.xmaven.controller"))
                    .build();
        }
    
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restful风格,http://www.xmaven.cn/")
                    .termsOfServiceUrl("http://www.xmaven.cn/")
                    .version("1.0")
                    .build();
        }
    }
  1. 写生成文档的注解

Swagger2 通过注解来生成API 接口文档,文档信息包括接口名、请求方法、参数、返回信息等。通常’悄况下用于生成在线API 文档,以下的注解能够满足基本需求,注解及其描述如下。
口@Api : 修饰整个类,用于描述Controller 类。
口@ApiOperation :描述类的方法,或者说一个接口。
口@ApiParam : 单个参数描述。
口@ApiModel :用对象来接收参数。
口@ApiProperty :用对象接收参数时,描述对象的一个字段。
口@ApiResponse: HTTP 响应的一个描述。
口@ApiResponses: HTTP 响应的整体描述。
口@Apilgnore :使用该注解,表示Swagger2 忽略这个API 。
口@ApiError : 发生错误返回的信息。
口@ApiParamlmplicit : 一个请求参数。
口@ApiParamsimplicit : 多个请求参数

  1. 创建Service层代码 代码如下:
public interface UserService {
    List<User> selectAll();

    User selectById(Long id);

    void deleteById(Long id);

    int updateUser(User user);

    int addUser(User user);
}
  1. 创建Service实现层代码 代码如下:
@Service
public class UserServiceImpl implements UserService {

    @Autowired
    UserMapper userMapper;

    @Override
    public List<User> selectAll() {
        return this.userMapper.findAll();
    }

    @Override
    public User selectById(Long id) {
        return userMapper.selectByPrimaryKey(id);
    }

    @Override
    public void deleteById(Long id) {
        userMapper.deleteByPrimaryKey(id);
    }

    @Override
    public int updateUser(User user) {
        return userMapper.updateByPrimaryKeySelective(user);
    }

    @Override
    public int addUser(User user) {
        return userMapper.insert(user);
    }
}
  1. 创建Controller 代码如下:
    通过@ApiOperation 注解描述生成在线文档的具体API 的说明,其中value 值为该接口的名称,notes 值为该接口的详细文档说明。这样就可以让Swagger2 生成在线的API 接口文档了。
    如果不需要某接扣生成文挡,只市要再加@Apilgnore 注解即可。
    @RestController
    @RequestMapping("/user")
    public class UserController {
    
        @Autowired
        UserService userService;
    
        @ApiOperation(value = "用户列表",notes = "用户列表")
        @RequestMapping(value = {""},method = RequestMethod.GET)
        public List<User> getUsers(){
            return userService.selectAll();
        }
    
        @ApiOperation(value = "创建用户",notes = "创建用户")
        @RequestMapping(value = "",method = RequestMethod.GET)
        public int postUser(@RequestBody User user){
            return userService.addUser(user);
        }
    
        @ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取详细信息")
        @RequestMapping(value = "/{id}",method = RequestMethod.POST)
        public User getUser(@PathVariable Long id){
            return userService.selectById(id);
        }
    
        @ApiOperation(value = "更新信息",notes = "根据url的id来更新指定用户信息")
        @RequestMapping(value = "/{id}",method = RequestMethod.PUT)
        public int putUsers(@PathVariable Long id , @RequestBody User user){
            User user1 = new User();
            user1.setName(user.getName());
            user1.setPassword(user.getPassword());
            user.setId(user.getId());
            return userService.updateUser(user1);
        }
    
        @ApiOperation(value = "删除用户",notes = "删除用户")
        @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
        public String deleteUsers(@PathVariable Long id ){
            userService.deleteById(id);
            return "success";
        }
    
        @ApiIgnore//使用该注解忽略这个API
        @RequestMapping(value = "/hi",method = RequestMethod.GET)
        public String jsonTest(){
            return "hi you!";
        }
    
    }
  1. 启动服务,浏览器访问: http://localhost:8090/swagger-ui.html 查看在线API

ME.png


下载链接:springboot-mybatis-druid-swagger.rar

0

评论区