自動(dòng)生成的接口文檔也可以清晰明了
web開發(fā)寫一個(gè)接口就需要添加一個(gè)接口文檔，又浪費(fèi)時(shí)間近上，接口文檔還不夠詳細(xì)拂铡，使用swagger2從此我再也不寫接口文檔了，自動(dòng)生成文檔斗锭，還讓人一看就清晰明了失球。
swgger2生成接口文檔步驟
- 使用maven引入swagger2接口自動(dòng)生成包
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.1</version></dependency>
-
注解說明
@Api：用在類上实苞，說明該類的作用。
@ApiOperation：注解來給API增加方法說明前硫。
@ApiImplicitParams : 用在方法上包含一組參數(shù)說明荧止。
@ApiImplicitParam：用來注解來給方法入?yún)⒃黾诱f明。
@ApiResponses：用于表示一組響應(yīng)
@ApiResponse：用在@ApiResponses中危号，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
-
@ApiModel：描述一個(gè)Model的信息（一般用在請(qǐng)求參數(shù)無法使用* @ApiImplicitParam注解進(jìn)行描述的時(shí)候）
- @ApiModelProperty：描述一個(gè)model的屬性
- 新建config包外莲，在包下新建swgger2配置類
package com.supermanshirts.config;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;@Configuration@EnableSwagger2public class Swagger2 { /** * 創(chuàng)建API應(yīng)用 * apiInfo() 增加API相關(guān)信息 * 通過select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來控制哪些接口暴露給Swagger來展現(xiàn)偷线， * 本例采用指定掃描的包路徑來定義指定要建立API的目錄沽甥。 * * @return / @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.supermanshirts.controller")) .paths(PathSelectors.any()) .build(); } /* * 創(chuàng)建該API的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁面中） * 訪問地址：http://項(xiàng)目實(shí)際地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("web接口自動(dòng)生成描述文檔，我再也不寫文檔了") .description("swagger2快速生成接口文檔示例") .termsOfServiceUrl("http://www.dadong.api") .contact(new Contact("will","","18201323192@163.com")) .version("1.0") .build(); }}
- 在參數(shù)實(shí)體類上添加注解
package com.supermanshirts.entity;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.Data;import java.io.Serializable;@Data@ApiModel(value="用戶對(duì)象模型")public class UserEntity implements Serializable { /用戶id/ private int m_id; /襯衫id/ private int shirt_id; /定制訂單id/ private int record_id; @ApiModelProperty(value="用戶名") /用戶名/ private String user_name; @ApiModelProperty(value="用戶密碼") /用戶密碼/ private String user_pass; /用戶頭像/ private String user_himg; /用戶昵稱/ private String nick_name; /用戶體型/ private String m_shape; /用戶腹部描述/ private String m_abdomen; /用戶肩部描述/ private String m_shoulder; public int getM_id() { return m_id; } public int getShirt_id() { return shirt_id; } public int getRecord_id() { return record_id; } public String getUser_name() { return user_name; } public String getUser_pass() { return user_pass; } public String getUser_himg() { return user_himg; } public String getNick_name() { return nick_name; } public String getM_shape() { return m_shape; } public String getM_abdomen() { return m_abdomen; } public String getM_shoulder() { return m_shoulder; } public void setM_id(int m_id) { this.m_id = m_id; } public void setShirt_id(int shirt_id) { this.shirt_id = shirt_id; } public void setRecord_id(int record_id) { this.record_id = record_id; } public void setUser_name(String user_name) { this.user_name = user_name; } public void setUser_pass(String user_pass) { this.user_pass = user_pass; } public void setUser_himg(String user_himg) { this.user_himg = user_himg; } public void setNick_name(String nick_name) { this.nick_name = nick_name; } public void setM_shape(String m_shape) { this.m_shape = m_shape; } public void setM_abdomen(String m_abdomen) { this.m_abdomen = m_abdomen; } public void setM_shoulder(String m_shoulder) { this.m_shoulder = m_shoulder; } public UserEntity() { } public UserEntity(int shirt_id, int record_id, String user_name, String user_pass, String user_himg, String nick_name, String m_shape, String m_abdomen, String m_shoulder) { this.shirt_id = shirt_id; this.record_id = record_id; this.user_name = user_name; this.user_pass = user_pass; this.user_himg = user_himg; this.nick_name = nick_name; this.m_shape = m_shape; this.m_abdomen = m_abdomen; this.m_shoulder = m_shoulder; }}
- 在應(yīng)用入口處掃描包
package com.supermanshirts;import org.mybatis.spring.annotation.MapperScan;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;//掃描包@SpringBootApplication(scanBasePackages = "com.supermanshirts")@MapperScan("com.supermanshirts.mapper")public class SupermanshirtsApplication { public static void main(String[] args) { SpringApplication.run(SupermanshirtsApplication.class, args); }}
- 在controller控制器中添加Api注解和方法接口注解
package com.supermanshirts.controller;import com.supermanshirts.entity.ResponseEntity;import com.supermanshirts.entity.UserEntity;import com.supermanshirts.service.UserService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RestController;@Api(value="用戶相關(guān)接口")@RestControllerpublic class UserController { @Autowired private UserService userService; @ApiOperation(value="用戶登錄",notes ="用戶登錄" ) @RequestMapping(value = "/login",method = RequestMethod.POST) public ResponseEntity get(UserEntity u){ ResponseEntity responseEntity=new ResponseEntity(); UserEntity userEntity=userService.getUser(u.getUser_name(),u.getUser_pass()); if(userEntity.getUser_pass().equals(u.getUser_pass())){ responseEntity.setStatus(200); responseEntity.setMsg("登錄成功"); responseEntity.setData(userEntity); }else { responseEntity.setStatus(300); responseEntity.setMsg("登錄失敗"); } return responseEntity; } /注冊(cè)用戶/ @ApiOperation(value="用戶注冊(cè)",notes = "用戶注冊(cè)") @RequestMapping(value = "/register",method = RequestMethod.POST) public ResponseEntity register(String username,String userpass){ ResponseEntity responseEntity=new ResponseEntity(); try{ String nickName="superman"+System.currentTimeMillis(); UserEntity userEntity=new UserEntity(0,0,username,userpass,"https://ss0.bdstatic.com/-0U0b8Sm1A5BphGlnYG/kmarketingadslogo/49b8e752ae9dbb3a5ed375f1185d7683_250_250.jpg",nickName,"標(biāo)準(zhǔn)體","扁腹","聳肩"); userService.insertUser(userEntity); responseEntity.setStatus(200); responseEntity.setMsg("注冊(cè)成功"); return responseEntity; }catch (Exception e){ responseEntity.setStatus(101); responseEntity.setMsg("注冊(cè)失敗"); return responseEntity; } } @RequestMapping(value = "/hello",method = RequestMethod.GET) public String test(){ return "hello springboot"; }}
6.運(yùn)行項(xiàng)目骗炉，在瀏覽器輸入http://localhost:8070/swagger-ui.html#/蛇受，可以看到swgger2為我們生成的文檔
