基于SpringBoot的Swagger2快速入门

1. Springboot 集成 Swagger2

　　1.1 导入Swagger2 依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

　　1.2 编写 Swagger 配置：如下简单添加注解即可访问SwaggerUi

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

　　1.3 访问http://localhost:8080/swagger-ui.html

2. 配置Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Swagger的Docket实例
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)    //关闭swagger
                .groupName("xxx")    //分组,多个分组需要多个Docket实例
                .select()    //接口过滤，扫描包名下的接口
                .apis(RequestHandlerSelectors.basePackage("cn.lcx.demo.controller"))
                .build();
    }

    /**
     * 配置Swagger信息
     * @return
     */
    private ApiInfo apiInfo(){

        Contact contact = new Contact("xxx","http://localhost:8080","xxxx@qq.com");
        return new ApiInfo(
                "xxx团队xxx项目api开发文档",
                "xxx团队xxx项目api开发文档",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

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

3. 编写Api文档注释

　　3.1 实体类

@ApiModel("用户实体类")    //注解在类上的api文档
public class User {
    @ApiModelProperty("用户名")    //注解在属性上的api文档
    private String username;
    @ApiModelProperty("密码")
    private String password;

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

    public void setPassword(String password) {
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public String getPassword() {
        return password;
    }
}

查看ui下面的model

　　3.2 接口类

@RestController
public class HelloController {

    @ApiOperation("获取用户接口")        //注解在方法名上的api文档
    @PostMapping("/user")
    //注解在变量上的api文档
    public User getUser(@ApiParam("用户名") String username, @ApiParam("密码") String password){
        return new User();
    }
}

查看ui的接口信息

4. Swagger2 还提供接口在线测试，功能类似postman