Home

NUNU

02 Nov 2018

Swagger使用指南

认识Swagger

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

作用：

    1. 接口的文档在线自动生成。
    1. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

    1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
    1. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
    1. Swagger-js: 用于JavaScript的Swagger实现。
    1. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
    1. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
    1. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

项目使用

例子中针对于java 的 maven spring boot 项目。

Maven 项目中pom.xml

新增

        <!-- swagger2 -->
        <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>

Swagger2Config

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

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("台风资源评估")
                .description("更多请关注 http://pnunu.cn/")
                .termsOfServiceUrl("http://pnunu.cn/")
                .contact("pnunu")
                .version("1.0")
                .build();
    }
}

xxx.xxx.controller

@Api(value = "XXX接口")
public class Controller  {

    @ResponseBody
    @RequestMapping(value = "upload")
    @ApiOperation(value="XXX文件的上传", notes="返回上传的文件XXX")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "upload", name = "id", value = "ID", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "file", name = "file", value = "XXXX文件", required = true, dataType = "File")})
    public Message uploadData(MultipartFile file, String id) throws TraException {
       ///////// code
    }

xxx.xxx.model

    @ApiModel(value = "dto", description = "XXX参数")
    public class Dto implements Serializable {
        private static final long serialVersionUID = 2095117945477337251L;
        @ApiModelProperty(value = "id", required = true)
        private String id;
        @ApiModelProperty(value = "name", required = false)
        private String name;
        @ApiModelProperty(value = "最大", required = true, example = "300")
        private long max = 300;
        @ApiParam(hidden = true)
        private String xxx = "xxx";
    }

常用注解

@Api：

作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。

参数：

    1. tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。
    1. description：可描述描述该类作用。

@ApiImplicitParam：

作用在方法上，表示单独的请求参数

参数：

    1. name ：参数名。
    1. value ： 参数的具体意义，作用。
    1. required ： 参数是否必填。
    1. dataType ：参数的数据类型。
    1. paramType ：查询参数类型，这里有几种形式：

@ApiImplicitParams：

用于方法，包含多个 @ApiImplicitParam

    @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
                @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})

@ApiModel：

用于类，表示对类进行说明，用于参数用实体类接收；

@ApiModelProperty：

用于方法，字段 ，表示对model属性的说明或者数据操作更改

@ApiModel(value = "User", description = "用户")
    public class User implements Serializable{

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "用户ID", required = true)
    protected String id;

    @ApiModelProperty(value = "code/登录帐号")
    protected String itcode;

    @ApiModelProperty(value = "用户姓名")
    @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
    protected String name;
 }

@ApiOperation：

用于方法，表示一个http请求的操作

@ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Book getBook(@PathVariable Long id, String date) {
        return books.get(id);
    }

@ApiResponse：

用于方法，描述操作的可能响应。

@ApiResponses：

用于方法，一个允许多个ApiResponse对象列表的包装器。

@ApiResponses(value = {
            @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
            @ApiResponse(code = 500, message = "403:没有权限"),
            @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})

@ApiParam：

用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

@Authorization：

声明要在资源或操作上使用的授权方案。

@AuthorizationScope：

介绍一个OAuth2授权范围。

@ResponseHeader：

响应头设置，使用方法。

业精于勤，荒于嬉； 行成于思，毁于随。
pnunu at 15:12

Flag Counter
‹ ›