Springboot+Swagger自动生成接口文档

Springboot+Swagger自动生成接口文档

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	
	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>1.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>
	
	<name>demo</name>
	<description>Demo project for Spring Boot</description>
	
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.1.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <fastjson.version>1.2.38</fastjson.version>
        <springfox.version>2.7.0</springfox.version>
        <guava.version>20.0</guava.version>
		<swagger-bootstrap-ui.version>1.9.3</swagger-bootstrap-ui.version>
		<springfox-swagger2.version>2.9.2</springfox-swagger2.version>
    </properties>

	<dependencies>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>
         </dependency>

         <!-- jstl JSP标准标签库  -->
		<dependency>
		    <groupId>javax.servlet</groupId>
		    <artifactId>jstl</artifactId>
		</dependency>
		<!-- 返回jsp页面还需要这个依赖 -->
		<dependency>
		    <groupId>org.apache.tomcat.embed</groupId>
		    <artifactId>tomcat-embed-jasper</artifactId>
		</dependency>

        <!-- fastjson -->
		<dependency>
		    <groupId>com.alibaba</groupId>
		    <artifactId>fastjson</artifactId>
		    <version>${fastjson.version}</version>
		</dependency>
		
		<!-- swagger 第一种风格 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${springfox.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${springfox.version}</version>
		</dependency>
		
		<!-- swagger 第二种风格 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${springfox-swagger2.version}</version>
			<exclusions>
				<exclusion>
					<groupId>com.google.guava</groupId>
					<artifactId>guava</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
			<version>${guava.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${springfox-swagger2.version}</version>
		</dependency>
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>${swagger-bootstrap-ui.version}</version>
		</dependency>

    </dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

主要是：
风格1 http://localhost:8080/swagger-ui.html

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>${springfox.version}</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>${springfox.version}</version>
</dependency>

风格2 http://localhost:8080/doc.html

<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${springfox-swagger2.version}</version>
			<exclusions>
				<exclusion>
					<groupId>com.google.guava</groupId>
					<artifactId>guava</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
			<version>${guava.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${springfox-swagger2.version}</version>
		</dependency>
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>${swagger-bootstrap-ui.version}</version>
		</dependency>

swagger有很多，也可以用其他包的，后面进行补充。

application.properties

 server.port=8080
# server.context-path:/demo

# springMVC
 spring.mvc.view.prefix=/WEB-INF/
 spring.mvc.view.suffix=.jsp
# spring.mvc.static-path-pattern=/static/**

config

/**
 * swagger配置@Configuration
 * @EnableSwagger2 Spring启动Swagger
 * http://localhost:8080/swagger-ui.html查看api
 * http://localhost:8080/doc.html
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        		.title("Swagger API文档")
                .description("SpringMVC+SpringBoot+Swagger2")
                .version("1.0.1")
        		.build();
    }

    @Bean
    public Docket customImplementation(){
        return new Docket(DocumentationType.SWAGGER_2)
        		.apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();        
    }

}

controller

/**
 * @Api 说明信息，可以省略
 * @RestController 就不用写@ResposeBody了
 */
@RestController
@Api(value="用户controller",description="用户相关操作",tags={"用户操作接口"})
public class UserController {
	
	private final Logger logger = LoggerFactory.getLogger(this.getClass());

	/**
	 * MVC请求
	 * @RequestMapping("/showUser") 则api文档会生成各种请求的此方法
	 * delete、get、head、options、patch、post、put、get
	 */
	@ApiOperation(value = "测试", notes = "随便跳转个页面")
    @RequestMapping("/showUser")
	public ModelAndView showUser(){
    	ModelAndView modelAndView = new ModelAndView("user");
	    return modelAndView;
	}
    
    /**
     * swagger测试，也可以返回Entity，swagger自动生成的页面都可以测试
     * http://localhost:8080/swagger-ui.html
              *  如果请求参数为对象，参数前@RequestBody@ApiParam()
	   *  对象类@ApiModel(description="用户对象user")
              *  变量@ApiModelProperty(value="状态",name="state",required=true)
              *  以上注解也可以省略，只是api页面的显示信息
     */
    @ApiOperation("获取用户信息ById")
    @RequestMapping("/getUser")
	public String getUser(@ApiParam(name="id",value="用户id",required=true) Integer id){
	    return JSON.toJSONString("Hello world!");
	}
    
}

启动类

/**
 * 此类放在最外面，SrpingBoot自带tomcat，直接运行此类启动服务
 * 需要注解@SpringBootApplication
 */
@SpringBootApplication
public class DemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

}

项目结构

启动项目。
风格1：访问http://localhost:8080/swagger-ui.html，可以看到自动生成的接口文档。
也可以直接进行测试。

风格2：访问 http://localhost:8080/doc.html。