Swagger2教程

作用：編寫和維護接口文檔。

一、Swagger2 + SpringBoot集成

1.依賴

    <!--依賴管理 -->
    <dependencies>
        <dependency> <!--添加Web依賴 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency><!--添加Swagger依賴 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency><!--添加Swagger-UI依賴 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency> <!--添加熱部署依賴 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <dependency><!--添加Test依賴 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

2.配置類

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                .title("公路施工管理系統接口文檔:")
                .description("用於道路施工管理")
                .contact(new Contact("a man who ",null, null))
                .version("Version: 1.0.0")
                .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demon.swagger2"))
                .paths(PathSelectors.any())
                .build();

    }
}

3.編寫接口文檔

Swagger2 基本使用：

• @Api 描述類/接口的主要用途

• @ApiOperation 描述方法用途

• @ApiImplicitParam 描述方法的參數

• @ApiImplicitParams 描述方法的參數(Multi-Params)

• @ApiIgnore 忽略某類/方法/參數的文檔

使用注解編寫文檔：

@Api("用戶信息管理")
@RestController
@RequestMapping("/user/*")
public class UserController {

    private final static List<User> userList = new ArrayList<>();

    {
        userList.add(new User(1, "Tom", "A fool cat"));
        userList.add(new User(2, "Jerry", "A clever mouse"));
    }

    @ApiOperation("獲取用戶列表")
    @GetMapping("list")
    public List userList() {
        return userList;
    }

    @ApiOperation("新增用戶")
    @PostMapping("add")
    public boolean add(User user) {
        return userList.add(user);
    }

    @ApiOperation("更新用戶")
    @ApiImplicitParam(name = "user", value = "單個用戶信息", dataType = "User")
    @PutMapping("update")
    public boolean update(User user) {
        return userList.remove(user) && userList.add(user);
    }

    @ApiOperation("批量刪除用戶")
    @ApiImplicitParam(name = "users", value = "N個用戶信息", dataType = "List<User>")
    @DeleteMapping("delete")
    public boolean delete(@RequestBody List<User> users) {
        return userList.removeAll(users);
    }
}

使用：http://localhost:9393/swagger-ui.html