spring boot整合swagger2, 搭建API在线文档

开发后台的工程师，实现和前端交互。给前端提供api,使用swagger2搭建在线api文档，接口文档信息一目了然

（1）引入依赖：

		
			io.springfox
			springfox-swagger2
			2.6.1
		

		
			io.springfox
			springfox-swagger-ui
			2.6.1
		

（2）配置swagger2:

写一个swagger2配置类：

 

package com.swagger2.config;

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;

/**
 * Created by xkx on 2017/5/27.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger2.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("https://mvnrepository.com/")
                .version("1.0")
                .build();
    }
}

（3）Controller编写生成文档的注解（此处没有连接真实的数据库）：

package com.swagger2.controller;

import com.swagger2.entity.User;
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.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by xkx on 2018/12/26.
 */
@RequestMapping("/user")
@RestController
public class UserController {
    @ApiOperation(value="用户列表", notes="用户列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List getUsers() {
        List users = new ArrayList<>();
        User user = null;
        for(int i=0; i<5; i++){
            user = new User();
            user.setId(((Integer)(i+1)).longValue());
            user.setUsername("zhangsan" + i+1);
            user.setPassword("psd" + i);
            users.add(user);
        }
        return users;
    }

    @ApiOperation(value="创建用户", notes="创建用户")
    @RequestMapping(value={""}, method= RequestMethod.POST)
    public User createUsers(User user) {
        return user;
    }
}

(4)效果图展示：

 

访问路径是自己配置的项目访问路径后面带上/swagger-ui.html

 

常用的swagger2 API文档注解：

 @Api：修饰整个类，描述Controller的作用 
@ApiOperation：描述一个类的一个方法，或者说一个接口 
@ApiParam：单个参数描述 
@ApiModel：用对象来接收参数 
@ApiProperty：用对象接收参数时，描述对象的一个字段 
@ApiResponse：HTTP响应其中1个描述 
@ApiResponses：HTTP响应整体描述 
@ApiIgnore：使用该注解忽略这个API 
@ApiError ：发生错误返回的信息 
@ApiImplicitParam：一个请求参数 
@ApiImplicitParams：多个请求参数
 

参考：深入理解Spring Cloud与微服务构建（方志鹏  著）