spring boot整和Swagger2 构建RESTful API 文档

1.什么是swagger？

• swagger是一个方便做 API文档的工具,可以很简洁的与springMVC程序配合。

2.swagger在springboot中的使用

2.1搭建spring项目项目

• 搭建项目名为swagger的springbot的maven项目

2.2.完成基本逻辑代码

项目基本结构

引入lombok

		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<version>1.16.14</version>
		</dependency>

/**
 * TODO 类描述  users
 *
 * @author honghe
 */

@Data
@Builder
public class User {
    private Long id;
    private String username;
    private String password;
}

/**
 * TODO 类描述
 *
 * @author honghe
 */
public interface UserService {

    User findUserById(Long id);


    List<User> findUserByName(String name);
}

/**
 * TODO 类描述
 *
 * @author honghe
 */
@Service
public class UserServiceImpl implements UserService {

    @Override
    public User findUserById(Long id) {
        return User.builder().id(id).username("admin"+id.toString()).password("123456").build();
    }

    @Override
    public List<User> findUserByName(String name) {
        List<User> users = new ArrayList<>();
        for (int i = 1; i <6 ; i++) {
            users.add(User.builder().id((long) i).username("admin-"+name).password("123456").build());
        }
        return users;
    }
}

2.3配置swagger

pom.xml引入swagger包

	<!-- 配置swagger-->
		<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>

创建swaggerConfig

/**
 * TODO 类描述
 *
 * @author honghe
 */
@Configuration
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
                .termsOfServiceUrl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }
}

配置静态资源路径

/**
 * TODO 类描述
 *
 * @author honghe
 */
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

}

创建控制器配置访问路径

/**
 * TODO 类描述
 *
 * @author honghe
 */
@Api(value="users",description="用户相关接口")
@RequestMapping("/users")
@Controller
public class UserController {
    @Autowired
    UserService userService;

    /**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/getUserById")
    @ResponseBody
    public Map<String,Object> findUser(Long id){
        Map<String,Object> result = new HashMap<>();
        try {
            User user = userService.findUserById(id);
            result.put("code",100);
            result.put("user",user);
        }catch (Exception e){
            result.put("code",101);
            result.put("message","查询失败！");
        }
        return result;
    }

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @ApiImplicitParam(name = "name", value = "用户民称", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/getUserByName")
    @ResponseBody
    public Map<String,Object> getUserByName(String name){
        Map<String,Object> result = new HashMap<>();
        try {
            List<User> userList = userService.findUserByName(name);
            result.put("code",100);
            result.put("user",userList);
        }catch (Exception e){
            result.put("code",101);
            result.put("message","查询失败！");
        }
        return result;
    }
}

3.访问API文档

http://localhost:8080/swagger/swagger-ui.html

git地址：https://gitee.com/zhaoershuang/swagger2.git