Swagger使用说明

需求

针对前后端分离框架，特别是当前后端为不同人员开发时，需要接口提供方（一般为后端开发团队）提供一份接口文档来描述接口内容。

需求：能不能在写代码时，一起生成接口文档。

解决方案

swagger

参考官网案例：点击进入

使用说明

引入依赖

// ${swagger.version} 为 2.9.2
<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

设置swagger接口文档配置

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

/**
 * @author guoyu.huang
 * @version 1.0.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 只扫描指定路径下的文件
                .apis(RequestHandlerSelectors.basePackage("xxx.xxx"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // url一定要以http或者https开头
        Contact contact = new Contact("XXX公司", "网站地址", "邮箱地址");
        return new ApiInfoBuilder()
                .title("XXXX系统")
                .description("XXXX系统API接口信息")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}

常用注解

Api

标记一个class文件作为swagger资源。一般用于控制器的类上。

@Api(tags = "项目管理API", produces = "application/json", protocols = "http")
@RestController
@RequestMapping(value = "/project")
public class ProjectRestController {

    ......
}

ApiModel & ApiModelProperty

• ApiModel为接口模型添加说明。一般用于VO或者DTO上。
• ApiModelProperty为接口模型中属性添加说明。

@ApiModel(description = "项目信息")
public class ProjectInfoDTO {

    @ApiModelProperty(value="项目编号", required = true)
    private String projectCode;

    @ApiModelProperty(value="项目名称", required = true)
    private String projectName;

    @ApiModelProperty(value="项目描述")
    private String projectDescribe;

    @ApiModelProperty(value="项目来源类型", required = true, allowableValues="itm-ITM系统导入,agility-系统注册,other-其他")
    private String projectSourceType;

    @ApiModelProperty(value="项目领导者")
    private String projectLeaderCode;

    @ApiModelProperty(hidden = true)
    private int status;
}

访问页面

http://ip:port/swagger-ui.html