mvc 显示序号_Spring-mvc项目的swagger接入及离线文档导出

step1.Spring boot接入swagger实在很简单，所以你应该是一个Spring mvc项目，然后又被改造之后需要向前端提供restful接口。

step2.添加swagger依赖：

 <dependency>
		  <groupId>io.springfox</groupId>
		  <artifactId>springfox-swagger2</artifactId>
		  <version>2.4.0</version>
	  </dependency>
	  <dependency>
		  <groupId>io.springfox</groupId>
		  <artifactId>springfox-swagger-ui</artifactId>
		  <version>2.4.0</version>
	  </dependency>

以上两个依赖就够了。

step3.到swagger的github下载项目，把dist文件夹放到你的Spring mvc项目的webapps目录下,名字改成swagger

step4:设置你的servlet，反正既然是spring-mvc项目，你肯定已经搞了servlet对伐，在你的servlet 配置xml下，设置：

<mvc:resources mapping="/swagger/**" location="/swagger/"/>
    <bean class="config.SwaggerController" />

这句话会让你的swagger资源请求不被拦截，注意文件夹的位置不能错啊。然后会把目前还没有写的(咦)swagger配置类注入。

在你的登录拦截器（如果有）配置下添加：

        <mvc:exclude-mapping path="/swagger/**"/>
        <mvc:exclude-mapping path="/v2/api-docs.do"/>

这两句话保证你的swagger在线接口不需要在线才能看。

step5.添加swaggerConfig，如下，直接抄吧,记得package也就是你需要在文档中显示的接口类所在的包，别搞错了:

package config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
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
@EnableSwagger2
@EnableWebMvc
public class SwaggerController extends WebMvcConfigurationSupport {

    public static final String SWAGGER_SCAN_BASE_PACKAGE = "controller.restful";

    @Bean
    public Docket customDocket() {
        //
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)).build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("", "", "");
        return new ApiInfo("后台API接口",//大标题 title
                "",//小标题
                "",//版本
                "",//termsOfServiceUrl
                contact,//作者
                "",//链接显示文字
                "e"//网站链接
        );
    }


}

step5.重启项目，在项目地址上可以看到启动的swagger，

step6(可选).如果l你还需要提供离线文档给前端的话，在pom中添加build/plugins/plugin：

<plugin>
             <groupId>io.github.swagger2markup</groupId>
             <artifactId>swagger2markup-maven-plugin</artifactId>
             <version>1.3.1</version>
             <configuration>
                 <swaggerInput>http://localhost:8080/v2/api-docs.do</swaggerInput><!---swagger-api-json路径-->
                 <outputFile>src/docs/asciidoc/generated/swagger</outputFile><!---生成路径-->
                 <config>
                     <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
                 </config>
             </configuration>
         </plugin>
		 <plugin>
			 <groupId>org.asciidoctor</groupId>
			 <artifactId>asciidoctor-maven-plugin</artifactId>
			 <version>1.5.6</version>
			 <configuration>
				 <!--asciidoc文件目录-->
				 <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
				 <!---生成html的路径-->
				 <outputDirectory>docs/asciidoc/html</outputDirectory>
				 <backend>html</backend>
				 <sourceHighlighter>coderay</sourceHighlighter>
				 <attributes>
					 <!--导航栏在左-->
					 <toc>left</toc>
					 <!--显示层级数-->
					 <!--<toclevels>3</toclevels>-->
					 <!--自动打数字序号-->
					 <sectnums>true</sectnums>
				 </attributes>
			 </configuration>
		 </plugin>

如上，两个plugin的地址别配错啊，不管是swgger的json输出地址还是导出文档的地址都不能错的哦。

swagger2markup会将我们的swagger导出json到指定路径，然后asciidoctor会将json转换成html格式的离线文档（也可以是其他格式啦）

调用maven run这两个依赖吧，顺序不能错哦：

导出的文档大概是这样:

二、swagger注解及最优实践

1. 强烈建议限制restful方法的接收请求类型为一种，如下所示

@RequestMapping(value = "/addRoleTask",method = RequestMethod.POST

2. 建议在controller上添加注解表名controller作用

@RestController
@RequestMapping("userTask")
@Api(tags ="用户任务关联接口")
public class UserTaskController extends BasicController

3. 建议在方法上添加注解标明方法作用

@ApiOperation(value = "添加角色--任务权限")
@RequestMapping(value = "/addRoleTask",method = RequestMethod.POST,produces = {"application/json;charset=UTF-8"})
public ResultVo<Integer> addRoleTask(@RequestBody  AddRoleTaskVO addRoleTaskVO){

4. 建议使用dto封装前端请求及后端返回

5. 建议在dto字段上添加注解说明每个字段的用处，可以使用代码生成器做这个工作，直接把数据库的注释取出来即可

@ApiModelProperty("角色id")
@Column( name="role_id")
private String roleId;

6. 在生产环境禁用swagger的方法

使用

@Profile("dev")

在swaggerConfig上，可以限制其只能在开发环境下运行，对应的jetty配置如下：

<configuration>
   <httpConnector>
      <port>10160</port>
   </httpConnector>
   <systemProperties>
      <systemProperty>
         <name>spring.profiles.active</name>
         <value>dev</value>
      </systemProperty>
   </systemProperties>
</configuration>

可以看到，只有当我们把这里的profile-active设成dev时，swagger才能正常运作。