Spring Boot整合Swagger-ui开发Restful api接口文档

Spring Boot整合Swagger-ui开发接口api文档

---

前言

使用spring boot对swagger进行整合，并使用合适的注解对接口进行说明注释，本文主要是对使用swagger的一个记录。

---

一、添加swagger依赖和配置

1.添加maven依赖

maven依赖如下：

<!-- swagger 依赖-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>

2.添加swagger配置类

配置类代码如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描的包文件目录
                .apis(RequestHandlerSelectors.basePackage("com.permission"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx")//文档标题
                .description("xxx")//文档描述
                //此处原先的contact(String)的方法已经弃用，需要构造一个新的Contact对象
                .contact(new Contact("name","url","email"))//文档作者详情
                .version("1.0")//版本
                .build();
    }
}

二、使用swagger注解

此步骤可以不做，但是不做的话会导致接口文档没有中文说明。

1.针对实体类

使用@ApiModel() 和@ApiModelProperty()
示例代码如下：

@ApiModel("测试vo")
public class TestVo {
    @ApiModelProperty("名字")
    private String name;
    @ApiModelProperty("性别")
    private String sex;
}

2.针对controller层的接口

使用@Api、@ApiOperation和@ApiParam居多，还有就是@ApiResponse和@ApiResponses

示例代码如下：

@Api(value = "测试接口",description = "测试接口")
@RestController
public class TestController {
	@ApiOperation(value = "hello接口",notes = "传入String类型的参数",response = TestVo.class)
    @GetMapping("/hello")
    public TestVo hello(@ApiParam("姓名") String name){}
	//一般上述的注解就可以适用于大多数地方

	//@ApiResponses就是包含了多个@ApiResponse，写法如下，还有其它的一些参数，但本人未使用过。
	@ApiResponses({
            @ApiResponse(code = 200,message = "正常",response = TestVo.class)
    })
}

---

三、页面效果

1.进入swagger的ui界面

//路径示例
http://localhost:8080/swagger-ui.html

2.效果展示

只用在实体类中用对应的注解，才会展示对应的字段提示