使用swagger2自动生成清晰明了的接口文档

自动生成的接口文档也可以清晰明了

web开发写一个接口就需要添加一个接口文档，又浪费时间，接口文档还不够详细，使用swagger2从此我再也不写接口文档了，自动生成文档，还让人一看就清晰明了。

swgger2生成接口文档步骤

1. 使用maven引入swagger2接口自动生成包

<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 : 用在方法上包含一组参数说明。

  • @ApiImplicitParam：用来注解来给方法入参增加说明。

  • @ApiResponses：用于表示一组响应

  • @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用* @ApiImplicitParam注解进行描述的时候）

  • @ApiModelProperty：描述一个model的属性

2. 新建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 { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， * 本例采用指定扫描的包路径来定义指定要建立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(); } /* * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("web接口自动生成描述文档，我再也不写文档了") .description("swagger2快速生成接口文档示例") .termsOfServiceUrl("http://www.dadong.api") .contact(new Contact("will","","18201323192@163.com")) .version("1.0") .build(); }}

3. 在参数实体类上添加注解

package com.supermanshirts.entity;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.Data;import java.io.Serializable;@Data@ApiModel(value="用户对象模型")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; }}

4. 在应用入口处扫描包

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); }}

5. 在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="用户相关接口")@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; } /注册用户/ @ApiOperation(value="用户注册",notes = "用户注册") @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,"标准体","扁腹","耸肩"); userService.insertUser(userEntity); responseEntity.setStatus(200); responseEntity.setMsg("注册成功"); return responseEntity; }catch (Exception e){ responseEntity.setStatus(101); responseEntity.setMsg("注册失败"); return responseEntity; } } @RequestMapping(value = "/hello",method = RequestMethod.GET) public String test(){ return "hello springboot"; }}

6.运行项目，在浏览器输入http://localhost:8070/swagger-ui.html#/，可以看到swgger2为我们生成的文档

swgger1.png
swagger2.png

我是爱分享的东东，求点赞求转发,你有什么好的推荐欢迎也分享给我吧，共分享共进步。

gitee代码下载