Spring Boot 使用 Swagger

创建SpringBoot项目

20181231210730.png

20181231210837.png

20181231210853.png

引入Swagger相关依赖

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置Swagger

package com.example.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
// 扫描ApiController的包
@ComponentScan(basePackages = "com.example.controller")
public class SwaggerConfig {
    @Bean
    public Docket customDocket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("zhuzhaofeng",
                "www.example.com",
                "zhuzhaofeng@aliyun.com");

        return new ApiInfoBuilder()
                .title("测试项目Api接口")
                .description("测试项目Api接口文档")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}

WebMVC配置

package com.example.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

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

编写一个Controller测试

这儿为了方便使用static 代码块初始化十个用户模拟数据库操作

package com.example.controller;


import com.example.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Api(value = "用户模块", description = "用户模块接口文档信息")
@RestController
public class UserController {

    public static List<User> users = new ArrayList<>();
    ;

    /**
     * 模拟数据
     */
    static {

        users.add(new User("01", "习大", "12345678"));
        users.add(new User("02", "武二", "12345678"));
        users.add(new User("03", "张三", "12345678"));
        users.add(new User("04", "李四", "12345678"));
        users.add(new User("05", "王五", "12345678"));
        users.add(new User("06", "赵六", "12345678"));
        users.add(new User("07", "宋六", "12345678"));
        users.add(new User("08", "杨八", "12345678"));
        users.add(new User("09", "韩九", "12345678"));
        users.add(new User("10", "孙十", "12345678"));
    }

    /**
     * 获取用户列表
     *
     * @return
     */
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
    @GetMapping("/users")
    public Map<String, Object> getUsers() {

        Map<String, Object> userMaps = new HashMap<>();

        userMaps.put("users", users);

        return userMaps;
    }
}

打开localhost:8080/swagger-ui.html 可以看到如下界面

20181231225154.png

20181231225250.png

20181231225311.png

20181231225327.png

20181231225349.png

可以看到数据全部展示出来了

接下来我们补全其他的方法

package com.example.controller;


import com.example.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Api(value = "用户模块", description = "用户模块接口文档信息")
@RestController
public class UserController {

    public static List<User> users = new ArrayList<>();
    ;

    /**
     * 模拟数据
     */
    static {

        users.add(new User("01", "习大", "12345678"));
        users.add(new User("02", "武二", "12345678"));
        users.add(new User("03", "张三", "12345678"));
        users.add(new User("04", "李四", "12345678"));
        users.add(new User("05", "王五", "12345678"));
        users.add(new User("06", "赵六", "12345678"));
        users.add(new User("07", "宋六", "12345678"));
        users.add(new User("08", "杨八", "12345678"));
        users.add(new User("09", "韩九", "12345678"));
        users.add(new User("10", "孙十", "12345678"));
    }

    /**
     * 获取用户列表
     *
     * @return
     */
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
    @GetMapping("/users")
    public Map<String, Object> getUsers() {

        Map<String, Object> userMaps = new HashMap<>();

        userMaps.put("users", users);

        return userMaps;
    }


    /**
     * 根据id获取单个用户信息
     *
     * @param id 用户id
     * @return
     */
    @ApiOperation(value = "根据id获取单个用户信息", notes = "根据ID查询某个用户的详细信息")
    @ApiImplicitParam(value = "用户id", paramType = "path")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable("id") String id) {

        User user = new User();

        for (User item :
                users) {
            if (item.getId().equals(id)) {
                user = item;
                break;
            }
        }
        return user;
    }
    @ApiOperation(value = "新增用户", notes = "根据传入用户参数，新增用户")
    @ApiImplicitParam(value = "用户对象", paramType = "query")
    @PostMapping("/add")
    public User addUser(User user) {
        users.add(user);
        return user;
    }
    @ApiOperation(value = "删除用户", notes = "根据传入用户id参数，删除对应用户")
    @ApiImplicitParam(value = "用户对象", paramType = "path")
    @DeleteMapping("/delete/{id}")
    public Object deleteUser(@PathVariable("id") String id) {
        for (User user :
                users) {
            if (user.getId().equals(id)) {
                return users.remove(user);
            }
        }
        return null;
    }
}

20181231225438.png

测试方法都相同