一 swagger简介

Swagger 是一个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可以跟据业务代码自动生成相关的api接口文档

具有以下好处

• 及时性 (接口变更后，能够及时准确地通知相关开发人员)

• 规范性 (能够规范表达接口的地址，请求方式，参数及响应格式和错误信息)

• 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)

• 可测性 (接口能够测试，以方便理解业务)

二使用方法

1 引入相应jar包（信用分系统使用springboot 1.5.5.RELEAS版本与swagger2.6.1版本适合）


            
         
          io.springfox
             
         
          springfox-swagger2
             
         
          2.6.1
         
        
            
         
          io.springfox
             
         
          springfox-swagger-ui
             
         
          2.6.1

2创建 swagger 配置类（在 springboot 启动类 Application.java 同级创建 Swagger2 的配置类 Swagger2 ）

@Configuration@EnableSwagger2public class Swagger2 {    @Value("${swagger.enable}")    private boolean enableSwagger;    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .enable(enableSwagger)                .select()                .apis(RequestHandlerSelectors.basePackage("com.xx.controller"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("信用分系统——api文档")                .description("让我们一起把信用分做好做强大")                .termsOfServiceUrl("http://wiki.lianjia.com/pages/viewpage.action?pageId=xxxx")                .version("1.0")                .build();    }}

3 在 controller 和 vo 上使用特定含义注解

@Api(description = "XX相关接口", tags = {"company"})@RestControllerpublic class XXController extends BaseController {    @Resource    private QueryCreditScoreCompService queryCreditScoreCompService;    @ApiOperation(value = "查询分公司列表", notes = "查询分公司列表")    @ApiImplicitParams({            @ApiImplicitParam(paramType = "query", name = "loginUserCode", dataType = "string", required = true, value = "登陆人系统号")    })    @ApiResponses({            @ApiResponse(code = 999, message = "后端代码异常"),            @ApiResponse(code = 404, message = "请求url路径错误，或者后端服务未部署启动"),            @ApiResponse(code = 0, message = "正常返回")    })    @RequestMapping(value = "/api/xx/query", method = RequestMethod.GET)    public JsonResult
        
         
          > queryCreditScoreCompList(String loginUserCode) {        return new JsonResult<>();    }}

vo模型上添加返回字段含义

@ApiModel("分公司信息")@Datapublic class CompDto {    @ApiModelProperty("城市编码")    private String cityCode;    @ApiModelProperty("城市名称")    private String compCode;    @ApiModelProperty("分公司编码")    private String cityName;    @ApiModelProperty("分公司名称")    private String compName;}

访问部署机器的ip+端口+swagger-ui.html，就能看到接口api页面

三各个注解用法说明：

注解	描述	解释
@Api	Marks a class as a Swagger resource.	用于类对象，只有在类对象上标注该注解后，相应的api信息才能展示出来.
@ApiOperation	Describes an operation or typically a HTTP method against a specific path.	描述具体的方法
@ApiImplicitParam	Represents a single parameter in an API Operation.	描述具体的请求参数，比如具体的响应方法的参数为 HttpServletRequest时，我会从该参数中取一些请求参数，则可以通过该方法单独定义参数.见下面的具体说明，该参数不能单独使用，必须和@ApiImplicitParams一起使用，可参考后面的例子
@ApiImplicitParams	A wrapper to allow a list of multiple ApiImplicitParam objects.	组合一组@ApiImplicitParam
@ApiParam	Adds additional meta-data for operation parameters.	定义具体的请求参数，类似@RequestParam 参数，直接在方法参数上使用.
@ApiResponse	Describes a possible response of an operation.	返回值，该类主要有code值与message两个属性，code值必须是http 返回code值，默认会有200，404等，不能单独使用，必须和@ApiResponses一起使用
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.	组合@ApiResponse
@ApiModel	Provides additional information about Swagger models.	提供对请求参数与返回结果中的model的定义