IDEA+SpringBoot整合Swagger2創建API文檔

------------恢復內容開始------------

1.創建SpringBoot項目

 

2.選擇快捷方式創建springboot項目

 

 

 

 

 

 

 

 

 3.工程文件樹形圖

 

 4.pom.xml中導入Swagger依賴

 

 代碼如下：

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

5.配置Swagger信息

 

 

 代碼如下：

package com.example.dell;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @program:swagger2-demo
 * @description:swagger配置類
 * @author:feixiang
 * @create:2020/5/14
 */

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.dell.web"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("飛翔用接口自動化平台")
                        .description("飛翔獨享")
                        .version("9.0")
                        .contact(new Contact("馬化騰","blog.csdn.net","[e-mail]"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

創建接口

接下來就是創建接口了，Swagger2相關的注解其實並不多，而且很容易懂，下面我來分別向小伙伴們舉例說明

 

 代碼如下

package com.example.dell.web;

import com.example.dell.pojo.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;



@RestController
@Api(tags = "用戶管理相關接口")
@RequestMapping("/user")
public class UserController{
    @PostMapping("/")
    @ApiOperation("添加用戶的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", defaultValue = "張三"),
            @ApiImplicitParam(name = "address", value = "用戶地址", defaultValue = "佛山", required = true)
    }
    )
    public RespBean addUser(String username, @RequestParam(required = true) String address) {
        return new RespBean();
    }

    @GetMapping("/")
    @ApiOperation("根據id查詢用戶的接口")
    @ApiImplicitParam(name = "id", value = "用戶id", defaultValue = "99", required = true)
    public User getUserById(@PathVariable Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }
    @PutMapping("/{id}")
    @ApiOperation("根據id更新用戶的接口")
        public User updateUserById(@RequestBody User user) {
        return user;
    }
}

這里邊涉及到多個API，我來向小伙伴們分別說明：

@Api注解可以用來標記當前Controller的功能。
@ApiOperation注解用來標記一個方法的作用。
@ApiImplicitParam注解用來描述一個參數，可以配置參數的中文含義，也可以給參數設置默認值，這樣在接口測試的時候可以避免手動輸入。
如果有多個參數，則需要使用多個@ApiImplicitParam注解來描述，多個@ApiImplicitParam注解需要放在一個@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中雖然可以指定參數是必填的，但是卻不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架內必填，拋棄了Swagger2，這個限制就沒用了，所以假如開發者需要指定一個參數必填，@RequestParam(required = true)注解還是不能省略。
如果參數是一個對象（例如上文的更新接口），對於參數的描述也可以放在實體類中。例如下面一段代碼：

 

 

package com.example.dell.pojo;

import io.swagger.annotations.ApiModelProperty;




public class User {
    @ApiModelProperty(value = "用戶id")
    private Integer id;
    @ApiModelProperty(value = "用戶名")
    private String username;
    @ApiModelProperty(value = "用戶地址")
    private String address;
    //getter/setter

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

 

 代碼如下：

package com.example.dell.web;

import io.swagger.annotations.ApiModelProperty;

public class RespBean {
    @ApiModelProperty(value = "用戶id")
    private Integer id;
    @ApiModelProperty(value = "用戶名")
    private String username;
    @ApiModelProperty(value = "用戶地址")
    private String address;
    //getter/setter

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

然后啟動，運行

 

 

 

 此時啟動項目，輸入http://localhost:8080/swagger-ui.html，能夠看到如下頁面，說明已經配置成功了：