Swagger 是一个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可以跟据业务代码自动生成相关的api接口文档
具有以下好处
1 引入相应jar包（信用分系统使用springboot 1.5.5.RELEAS版本与swagger2.6.1版本适合）
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
|
2创建 swagger 配置类（在 springboot 启动类 Application.java 同级创建 Swagger2 的配置类 Swagger2 ）
@Configuration
@EnableSwagger2
public 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.lianjia.credit.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("信用分系统——api文档")
.description("让我们一起把信用分做好做强大")
.termsOfServiceUrl("http://wiki.lianjia.com/pages/viewpage.action?pageId=169935067")
.version("1.0")
.build();
}
}
|
3 在 controller 和 vo 上使用特定含义注解
@Api(description = "分公司相关接口", tags = {"company"})
@RestController
public class CreditScoreCompController 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/comp/query", method = RequestMethod.GET)
public JsonResult<List<CompDto>> queryCreditScoreCompList(String loginUserCode) {
return new JsonResult<>();
}
}
|
vo模型上添加返回字段含义
@ApiModel("分公司信息")
@Data
public 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的定义 |
原文：https://www.cnblogs.com/wanghongsen/p/9376852.html