日常我們開發(fā)完后端接口帐偎，如果是返回restful，寫API文檔是免不了的御雕，Swagger可以幫我們解決大多數(shù)問題（自動(dòng)生成API文檔）矢沿。
他會(huì)幫我們生成一個(gè)html頁面，大概就是這個(gè)樣子酸纲。
好了咨察，開始正文，如果你覺得有需要的話福青，往下看摄狱。
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. 修改啟動(dòng)項(xiàng)
添加注解
@EnableSwagger2 //開啟swagger文檔生成
3. 給Controller或者字段添加注釋
3.1 給Controller方法添加注釋。
@ApiOperation(value = "條件查詢用戶")
@GetMapping("/user")
@JsonView(User.UserSimpleView.class)
public List query(UserQueryCondition condition,
@PageableDefault(page = 2,size = 7,sort = "username,asc")Pageable pageable){
System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.DEFAULT_STYLE));
List<User> users = new ArrayList<>();
users.add(new User());
users.add(new User());
users.add(new User());
return users;
}
然后訪問http://127.0.0.1:8080/swagger-ui.html
3.2 給方法中的字段添加注釋
方法一：
@RequestMapping("/user/{id:\\d+}")
@ApiImplicitParam(name = "id",value = "用戶id")
public User getInfo( @PathVariable String id){
User user = new User();
user.setUsername("FantJ");
return user;
}
方法二：
@RequestMapping("/user/{id:\\d+}")
public User getInfo(@ApiParam("用戶id") @PathVariable String id){
User user = new User();
user.setUsername("FantJ");
return user;
}
方法一是再方法上面加注解无午，方法二是再參數(shù)位加注解媒役。
3.3 給實(shí)體類的屬性添加注釋
@ApiModelProperty("用戶名")
private String username;
最后所有注解的總結(jié)
- @Api：修飾整個(gè)類，描述Controller的作用
- @ApiOperation：描述一個(gè)類的一個(gè)方法宪迟，或者說一個(gè)接口
- @ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
- @ApiModel：用對(duì)象來接收參數(shù)
- @ApiProperty：用對(duì)象接收參數(shù)時(shí)酣衷，描述對(duì)象的一個(gè)字段
- @ApiResponse：HTTP響應(yīng)其中1個(gè)描述
- @ApiResponses：HTTP響應(yīng)整體描述
- @ApiIgnore：使用該注解忽略這個(gè)API
- @ApiError ：發(fā)生錯(cuò)誤返回的信息
- @ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
- @ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
生產(chǎn)中遇到的問題集錦
1. url是127.0.0.1，但是服務(wù)在云主機(jī)上次泽。
那如何來配置這個(gè)url呢穿仪？我們添加一個(gè)配置類
package com.tyut.web.config;
import io.swagger.annotations.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
/**
* Created by Fant.J.
* 2018/4/30 17:20
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.tyut.web.controller";
public static final String VERSION = "1.0.0";
ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger API")
.description("This is to show api description")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.termsOfServiceUrl("")
.version(VERSION)
// .contact(new Contact("","", "844072586@qq.com")) 聯(lián)系方式
.build();
}
@Bean
public Docket customImplementation(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.build()
.host("47.xxx.xxx.96")
.directModelSubstitute(org.joda.time.LocalDate.class, java.sql.Date.class)
.directModelSubstitute(org.joda.time.DateTime.class, java.util.Date.class)
.apiInfo(apiInfo());
}
}
2. 修改controller描述
在controller上加注解@Api(description = "公告API")
介紹下我的所有文集：
流行框架
SpringCloud
springboot
nginx
redis
底層實(shí)現(xiàn)原理：
Java NIO教程
Java reflection 反射詳解
Java并發(fā)學(xué)習(xí)筆錄
Java Servlet教程
jdbc組件詳解
Java NIO教程
Java語言/版本 研究
