Integrated use of Springfox and swagger

First, preface

Let's take a look at the relationship between Springfox and swagger first .

Swagger api api declaration "( OPENAPI specification oas api

Oas api specification, which describes a complete set of api interface, including an interface that is get or post request Ah, what are the parameters which header Ah, will be included in this file. It is usually designed to be yaml format, which is more convenient to write. The transmission in the network will be the json Span style= "Font-family:calibri" >json

because spring marty Pitt wrote a based on spring component swagger-springmvc swagger integrated into springmvc springfox springfox springfox-swagger2

Pringfox-swagger2 remains dependent on the OSA Specification document, which is a JSON file that describes the API , And the function of this component is to help us to automatically generate this JSON file, we will use another component springfox-swagger-ui this JSON The file is parsed out and presented in a more friendly way.

This is the introduction, we simply introduce the configuration of Springfox-swagger2, to help you to achieve the smooth use of the text, there are many of their own understanding, if there are errors, welcome criticism.

Ii. description of the configuration process

Before we start coding, we have a general understanding of the configuration process.

In the preface, we know that our first task is to generate a that satisfies the osa specification. Span style= "Font-family:calibri" >json file (of course, create a spring springfox docket (abstract meaning) class, we need to make it a bean injected to spring Obviously, we need a configuration file, and in a way (obviously it will be an annotation) tells the program that this is a swagger configuration file.

one osa specification document needs a lot of information to describe this api Springfox allows us to synthesize an information group into a apiinfo docket (you can of course not construct this class, but directly use null but your this api low ).

Next, we're going to write the controller, of course it doesn't matter, no springfox You still have to write the controller, It is important to tell springfox This controller is a need for him to collect api The controller of information, needless to say, this still takes the form of annotations, at the same time, In order to combine the configuration file with the controller, we need to indicate where in the configuration file the collection might be api Controller information.

here, generate osa canonical json file configuration is over. Although the build process is more complex than I have described, these programs will help us, and we can do this by using a similar http://localhost:8080/demo/v2/ Api-docs json Span style= "font-family: Song body" > file. This v2/api-docs springfox The default path of the generated document.

Next, we need to visualize it, if we use Swagger-springmvc, we need to download a swagger UI Display page, and change the path to the above Http://localhost:8080/demo/v2/api-docs, here you can feel thattheswagger UI is parsing a JSON file. You can still do this, but Springfox has a dedicated springfox-swagger-ui component that doesn't need to be configured, We only need to introduce this dependent component to see the final effect, and this route will be http://localhost:8080/demo/swagger-ui.html.

Iii. Introduction of dependency

If I write well, believe to see here, you have a general understanding of the use of Springfox swagger2 flow. Well, let's go into the first step of formal coding: introducing dependencies.

Here we use maven to introduce dependencies, you can search for springfox on http://mvnrepository.com , You can see the springfox Swagger2 and springfox Swagger Ui, and then you can get the latest resources from it. as follows:

<Dependency>    <groupId>Io.springfox</groupId>    <Artifactid>Springfox-swagger2</Artifactid>    <version>2.7.0</version></Dependency><Dependency>    <groupId>Io.springfox</groupId>    <Artifactid>Springfox-swagger-ui</Artifactid>    <version>2.7.0</version></Dependency>

Also requires a dependent component:

<Dependency>       <groupId>Com.fasterxml.jackson.core</groupId>      <Artifactid>Jackson-databind</Artifactid>      <version>2.6.6</version></Dependency>

四、一个 a simple configuration file

In order to be clear, we can first build a config directory in the common source package , and create a swaggerconfig.java file in it, which is a spring configuration file, so the location and file name are not very significant.

First on the code (refer to the blog http://blog.csdn.net/u012476983/article/details/54090423 here):

@Configuration//must exist@EnableSwagger2//must exist@EnableWebMvc//must exist@ComponentScan (basepackages = {"Com.xiaoming.SpringMVC.controller"})//Scan API Controller package name must be present can also scan class directly (basepackageclasses) Public classswaggerconfig{@Bean PublicDocket Customdocket () {return NewDocket (documentationtype.swagger_2). Apiinfo (Apiinfo ()); }    Privateapiinfo Apiinfo () { Contact Contact=NewContact ("Xiao Ming", "http://www.cnblogs.com/getupmorning/", "[email protected]"); return NewApiinfobuilder (). Title ("Foreground API Interface"). Description ("Foreground API Interface"). Contact. Version ("1.1.0"). build (); }}

as you are sure to use IDE, you don't write all kinds of import here .

First, this Swaggerconfig class has four annotations, see the name can understand what the meaning. Among them,@Configuration,@EnableWebMvc and @ComponentScan are Spring the annotations, and @EnableSwagger2 is used to start the Swagger support, indicating that this is a Spring Swagger 's configuration file.

after that, you define aBeanMethodCustomdocket,SpringThe name doesn't matter, it's important to return aDocketclass,documentationtype.swagger_2as aDocketparameter of the constructor method, specifying theSwaggerversion2.0, the official website is already in the trailer3.0version of the. And then theApiinfois to invoke the nextApiinfofunction to create aDocketthe information. Apiinfofunction takesApiinfobuilderto createApiinfoclass.

How far Controller

In fact, the controller does not need to be configured, it will already be recognized by the Springfox Swagger , but here we symbolically add a descriptive message:

@Controller @requestmapping ("/test")  Public class TestController {    @ApiOperation (value= "One Test API", notes = "First Test API")    @ResponseBody    = "/hello", method = requestmethod.get)    public  String Hello ()    {          return "Hello";    }}

There is just one more @ApiOperation annotation, and the other is exactly the same as a normal SPRINGMVC Controller.

In fact, in order to form a complete API document, you need to add a lot of annotations, if it is written in the same file will appear bloated, we often write an interface file, the annotations are placed in the interface file, and then use an entity class to implement the controller, It is the implementation of the configuration and logical separation.

Vi. viewing interface files and documents

If there is no problem, you can now deploy the project and open Http://localhost:8080/demo/v2/api-docs:

Firefox provides a plugin to view JSON , we recommend that you try it.

Needless to say, there is a lot of information that you can see before you configure it. Inject description,version,title , etc. And it does have testcontroller information.

Finally, we open the http://localhost:8080/swagger-ui.html, we can see a beautiful interface:

Integrated use of Springfox and swagger