Swagger入门学习及其使用笔记

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

与postman相比，postMan能更全面的测试接口，支持更多的数据类型请求。

SpringBoot集成Swagger

1、导入依赖

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

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

新版的（springboot3.0）：

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>

2、配置swagger

3.0版本后不需要在加入@enableswagger2这个注解

@Configuration
@EnableSwagger2 
public class swaggerconfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .protocols(Collections.singleton("https"))
                .host("192.168.0.106:8088") //前端请求到的后端地址
                .apiInfo(apiInfo()) //配置api信息
                .groupName("小育")  //指定分组名。有多个docker就有多个分组就有多个名字
                .enable(true)//eanble决定了是否启动swagger，发布时记得关掉
                .select()  //指定我们需要基于什么包扫描
                .apis(RequestHandlerSelectors.basePackage("com.minzheng.blog.controller")) //指定接口所在的包
                //apis:
                //RequestHandlerSelectors扫描接口的方式
                //basePackage指定扫描包
                //any（）扫描全部
                //none（）不扫描
                //withclassannotation 扫描类的注解（里面必须放注解的反射对象）
                .paths(PathSelectors.any())
                //path：过滤哪里什么路径
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("博客api文档") //文档标题
                .description("springboot+vue开发的博客项目") //文档简介
                .termsOfServiceUrl("http://192.168.0.106:8084/")//前端地址
                .version("1.0")
                .build();
    }

}

启动访问路径查看接口文档：Swagger UI

例如：http://localhost:8088/swagger-ui.html

服务器地址加上 swagger-ui.html 后缀即可访问到

获取json格式的api文档：localhost:8088/v2/api-docs

Swagger注解

这些注解用来给视图层、控制层数据注解, 方便生成接口文档

用来解释视图层类的用 @Apimodel

@ApiModel("用户信息实体类") 
public class User{ 
}
或：
@ApiModel(description = "查询条件")

用来解释视图层类中的属性用 @ApiModelProperty()

@ApiModelProperty(name = "current", value = "当前页码", required = true, dataType = "Integer")
private Integer current;

用来给控制层类描述的 @Api(tags = “分类模块”)

用来给控制层响应方法描述的 @ApiOperation(value = “删除角色”)

用来给控制层响应方法单个参数描述的@ApiImplicitParam(name = “current”, value = “当前页码”, required = true, dataType = “Long”)

Swagger总结

1. Swagger最重大的使命就是使前后端人员之间的和谐关系有所好转
2. 接口文档可以实时更新
3. 可以在线测试后端接口，这个功能好评，爽的一批

Swagger是一个十分好用的工具，很多公司在使用

PS：处于安全考虑，我们在发布的时候需要关闭Swagger