Swagger接口文档生成及使用

一，什么是Swagger

Swagger是一个规范和完整的框架，用于生成，描述，调用和可视化 RESTful风格的WEB服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

Swagger的作用：

1，接口的文档在线自动生成。

2，功能测试。

二，在Maven中添加依赖

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.2.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.2.2</version>

</dependency>

三，创建Swagger2的配置类


/**

* Swagger2配置类

* 在与spring boot 集成时，放在与Application.java同级的目录下

* 通过@Configuration注解，让spring来加载该配置

* 再通过@EnableSwagger2注解来启动Swagger2

* @author sr

* 2018-1-12

*/

@Configuration

@EnableSwagger2

public class SwaggerConfig {

@Value("${my.swagger2.enable}")

private boolean enable;

    private static final StringbasePackage ="com.ulearning.ulms";

    /**

* 创建API应用

* appinfo()增加API相关信息

* 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现

* 本例采用置顶扫描的包路径来定义指定要建立API的目录

    * @return

    */

    @Bean

    public DocketuserApi() {

Predicate swaggerSelector = RequestHandlerSelectors

.withMethodAnnotation(ApiOperation.class);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage(basePackage))

.apis(swaggerSelector).paths(PathSelectors.any()).build()

.enable(enable);

    }

/**

* 创建API的基本信息（这些基本信息会展示在文档页面中）

* 访问地址：http://项目实际地址/swagger-ui.html

    * @return

    */

    private ApiInfoapiInfo() {

return new ApiInfoBuilder().title("直播平台")

.description("直播平台文档,行业开放接入")

.license("QA").licenseUrl("qa.html")

.contact(new Contact("sr", "", ""))

.version("1.0.1").build();

    }

}

Swagger2的注解使用：

@Api:用在类上，说明该类的作用。

image

@ApiOperation:注解来给API增加方法说明。

image

@ApiImplicitParams:用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses: 用于表示一组响应。

@ApiResponse: 用在@ApiResponses中，一般用于表达一个错误的响应信息。

code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

*  @ApiModelProperty：描述一个model的属性

最后编辑于：2019.06.10 16:28:36